secure-77/Perlite: Web Markdown Viewer for Obsidian Vaults

Perlite Vault Structure and Obsidian Compatibility

Perlite addresses a specific publishing problem: an Obsidian vault is organized as a local collection of Markdown files, links, tags and folders, but those files are not automatically arranged as a browsable website. Perlite places the vault in a web directory and builds the reader interface from that directory structure. The README describes this as an open source alternative to Obsidian Publish.

The intended users are people who already maintain notes in Obsidian or a related Markdown folder structure and want a web presentation without converting every note into a separate site-building format. The repository lists automatic construction from the vault structure, links to the vault, Obsidian tags, images, previews, search, responsive layout and dark and light mode. Perlite also documents support for Obsidian Canvas, LaTeX and Mermaid.

The design is file-centered rather than database-centered. No database is required, which keeps the deployment closer to static hosting plus a PHP application. However, it does not mean that a deployment is automatically safe or entirely static. The application parses content through PHP, and the README specifically warns about direct access to Markdown files and metadata.json. That distinction matters for vaults containing private material.

Perlite Request Flow and Server Components

The documented deployment uses two containers. The `perlite` service runs `sec77/perlite:latest`, and the `web` service runs `nginx:stable`. The notes service receives a read-only mount at `/var/www/perlite/Notes`, while `NOTES_PATH: Notes` tells the application where those notes are inside that service. Nginx exposes port 80 on the host and loads its configuration from `./web/config/perlite.conf`.

The data flow implied by the repository is therefore filesystem based. The host's `NOTES_PATH`, or `./perlite/Demo` by default, is mounted into the Perlite container. Perlite reads the vault and constructs its metadata and navigation, while Nginx serves the web application. The compose file uses `restart: unless-stopped` for both services and declares `web` as dependent on `perlite`.

The README also documents Safemode from Parsedown. It states that Safemode is active, but recommends against allowing untrusted user input. This is an explicit limitation of the publishing model. Perlite is better suited to notes controlled by the vault owner than to a service where arbitrary visitors can submit Markdown that the server parses.

Perlite Docker Installation and First Vault

The README says to read the required Obsidian settings before installation, then points Docker users to `perlite/Demo/Documentation/01-Docker-Setup.md`. The repository provides a `docker-compose.yml`, an optional `.env`, and a sample Demo vault. The compose file shown below is the documented deployment shape. The README does not give a one-line startup command, so no command that is not present in the repository is added here.

Before starting, copy `.env.example` to `.env` as instructed by that file and adjust `NOTES_PATH`, `VAULT_NAME` and `HOME_FILE`. For Docker, `NOTES_PATH` is the host path mounted into the container. The default is `./perlite/Demo`:

NOTES_PATH=./perlite/Demo
VAULT_NAME=Demo
HOME_FILE=README
SITE_TITLE=Perlite

The Docker Compose file then mounts that host directory read-only:

volumes:
  - ${NOTES_PATH:-./perlite/Demo}:/var/www/perlite/Notes:ro

The application receives the corresponding container path:

environment:
  NOTES_PATH: Notes

Nginx publishes the web interface on port 80. The compose file binds the host port directly:

ports:
  - 80:80

After the services are started according to the linked Docker setup documentation, open the Perlite URL. The first page is determined by `HOME_FILE`, which defaults to `README` in `.env.example`. The README says the page builds itself from the folder or vault structure, so the first real use is to place or mount a Markdown folder and inspect the generated navigation, links and search rather than convert notes manually.

Perlite Search, Graph, Theme and Navigation Controls

Perlite exposes common note-browsing features through configuration rather than requiring a separate content database. Search is listed as a built-in feature, and the local graph can be enabled or disabled with `SHOW_LOCAL_GRAPH`. The table of contents is controlled by `SHOW_TOC`, while `SHOW_TOC=true` is the default in `.env.example`.

Obsidian support is broader than plain Markdown rendering. The README lists tags, links, images, previews, LaTeX, Mermaid and Canvas support. The application also provides a full interactive graph. The graph is based on the vault's note links, with metadata generated by the PHP engine. That makes graph quality dependent on the notes containing usable links and on the vault being mounted correctly.

Presentation settings include `LINE_BREAKS`, `DISABLE_POP_HOVER`, `NICE_LINKS`, `FONT_SIZE`, and `TREE_VISIBLE_EXTENSIONS`. The default examples show single-line breaks being converted to `<br>`, link previews enabled, full paths hidden in favor of file names, and non-Markdown files such as PDFs or DOCX files visible in the navigation. The README does not specify every browser setting or the exact graph configuration options, so those details must be taken from the linked documentation rather than inferred from the feature list.

Perlite Security Boundaries and Excluded Vault Content

The clearest limitation is that Perlite does not treat an exposed vault as harmless by default. The README warns that Markdown files should not be directly accessible through the browser. It suggests that only the PHP engine should have access to them, or that the server should at least ensure Markdown files are downloaded rather than rendered by the browser. It gives the same warning for metadata.json.

Metadata is especially relevant when the public site excludes some files or folders. The README states that metadata.json contains the whole Obsidian structure. Even when Perlite checks that a requested path exists inside the provided vault, excluded files may still be present in metadata.json. As a result, hiding a folder in the UI is not equivalent to removing its information from every generated artifact.

The `.env.example` file includes `HIDDEN_FILE_ACCESS=false` and describes it as controlling access to Markdown files in hidden folders. It also includes `HIDE_FOLDERS`, with `docs,private,trash` as an example. These settings can shape presentation, but the README's security guidance remains necessary. A deployment should verify that direct requests cannot retrieve Markdown, metadata or excluded content. Safemode reduces some Parsedown risks, but the maintainer explicitly does not recommend untrusted user input.

Perlite Alternatives and Deployment Trade-offs

Obsidian Publish is the direct alternative named by the README. Perlite is self-hosted source code that reads a vault mounted into a web server, offers a no-database, file-oriented path, and documents Docker and non-Docker setup paths. The README does not provide a feature-by-feature comparison beyond naming Obsidian Publish as an alternative.

A static Markdown site generator is another different approach. Such a generator generally converts notes into deployable pages during a build, whereas Perlite reads the mounted vault through its PHP application and generates the browser experience from that content. Perlite can therefore suit workflows where the vault remains the primary artifact and the web directory is updated through a mount. The trade-off is that the PHP runtime and web-server exposure remain part of the security boundary.

Perlite is the wrong choice for an anonymous Markdown upload service, a multi-tenant editor, or a vault whose private files must be hidden without server-level access controls. It is also less suitable when a fully static deployment with no server-side parsing is a hard requirement. The README does not claim anonymous editing or multi-user permissions, so those capabilities should not be inferred.

Perlite Maintenance, Licensing and Upgrade Work

The repository is not archived, and its last push was on 2026-10-14. The release history includes versions 1.6.3 on 2026-10-01, 1.6.2 on 2026-09-30 and 1.6.1 on 2026-01-21. These dates indicate recent repository activity, but the README does not promise a particular support window or compatibility policy. Upgrade planning should therefore account for changes to Parsedown behavior, PHP parsing, Nginx configuration, Obsidian syntax handling and the generated metadata format.

The project is released under the MIT License. That permits use and modification under the terms of the license, but the README and supplied repository files do not provide legal interpretation. Operators should review the `LICENSE` file and account for the licenses of any dependencies and container images used in the deployment.

The compose file uses the moving tag `sec77/perlite:latest` and `nginx:stable`. Those tags simplify initial deployment but do not pin an exact release. A reproducible deployment would need an explicit version choice made by the operator, followed by review of `Changelog.md`, the linked documentation and the required Obsidian settings. The repository's contribution instructions send pull requests to the `dev` branch, which is a separate workflow from ordinary upgrades.

Editorial conclusion

Perlite fits teams or individuals who want to publish a controlled Markdown or Obsidian vault through a web server and can protect sensitive files. It is not suitable for untrusted note input or for deployments that leave vault files and metadata directly accessible. Verify the NOTES_PATH mapping, hidden-folder rules, web-server access restrictions and required Obsidian settings before adopting it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. secure-77/Perlite on GitHub