Docs
The Docs module is currently in private beta.
The Docs module is for structured content — guides, references, tutorials, or even a whole book. Pages are organized in a tree that maps directly to your folder structure. The site you're reading right now is built with it.
Anatomy of a Doc Page
- Title
The filename of the note. You'll be asked for it when creating a page via the plugin commands. - Description
A short summary set in thedescriptionfield of the frontmatter. It shows up in search engine results and social media previews. Don't skip it! - Body
Everything below the frontmatter. See the Content section for formatting, images, code blocks, and other supported elements.
Page Lifecycle
Every page has a status in its frontmatter. Before a page goes live, this is mostly for organizing your writing workflow. After a page goes live, its public status is managed on Draftist and pulled back to Obsidian.
- Draft — work in progress, can be previewed on your site but not visible to readers.
- Published — live on your site.
- Unpublished — taken offline because it needs more work; publish it again when ready.
- Archived — taken offline because it is no longer relevant; unarchive it if needed.
- Deleted — in trash on Draftist, scheduled for deletion; restore it or delete it permanently. If the page was permanently deleted on Draftist, the local note keeps
status: Deletedbut its Draftist metadata is removed.
Once a page has gone live, manage its status on Draftist — use the toolbar on the preview site. To get there, run Draftist: Manage on Draftist command. The plugin pulls the live status back to Obsidian.
Unpublished and Archived are both offline, but they mean different things. Use Unpublished when something went live too soon and still needs work. Use Archived when the content is no longer relevant and is expected to stay out of the live site.
Doc pages also depend on their ancestors. If a parent page is unpublished, archived, or deleted, published child pages are hidden from the live site until the parent is restored.
Folder Structure
Folder nesting defines the page hierarchy, and numeric prefixes reflect ordering. Each folder follows the NN - Title pattern — the prefix sets the position in the file tree. These only exist to keep things sorted in Obsidian's file explorer; the actual order on your site is tracked separately. The plugin assigns prefixes automatically when you create pages, so you don't need to worry about them.
There are two kinds of entries: pages and groups. A page has content. A group is a section label that organizes child pages — it shows up in the sidebar but doesn't have its own page (though it might). To make a group, just leave the note's body empty. A page with children works too — it serves as both a section and a standalone page.
My Website/
└── Docs/
├── 01 - Getting Started/
│ ├── Getting Started.md
│ ├── 01 - Installation/
│ │ └── Installation.md
│ └── 02 - Configuration/
│ └── Configuration.md
├── 02 - Guides/
│ ├── Guides.md
│ └── 01 - Writing Content/
│ └── Writing Content.md
└── 03 - Reference/
└── Reference.mdThe Docs folder name must match the module name in your site settings.
Each page lives in its own folder — the markdown file and all its assets are kept together:
01 - Getting Started/
├── Getting Started.md
└── images/
├── doc-screenshot.a1b2c3d4.png
└── ...When you rename a page file, the plugin automatically renames its folder to match. When you delete a page folder, sibling folders are automatically renumbered to keep the sequence clean.
Creating a Page
Open the command palette (Ctrl/Cmd + P) and run Draftist: Create new doc page. Pick a location in the tree, enter a title and description, and the plugin creates the folder with the correct prefix and a note with pre-filled frontmatter.
You can also right-click a folder in the file explorer and use either "Add page before", "Add page after", or "Add child page".
Adding Images
All images are stored in the page's images/ subfolder — the plugin handles this automatically when you add assets via the provided commands. If you've added images manually or they ended up outside the images/ folder, run Draftist: Normalize images to reorganize them into the correct location with consistent filenames.
Frontmatter
Here are the frontmatter fields the plugin manages:
| Field | Description |
|---|---|
status | Page lifecycle stage: Draft, Published, Unpublished, Archived, or Deleted |
description | Short summary shown in SEO meta tags |
posted on | Publication date (YYYY-MM-DD). Auto-assigned on first publish if not set. |
slug | Custom URL slug. Auto-generated from the title if not set. |
tags | List of tags |
collapsed | When set to true, the page's children are collapsed in the sidebar by default |
If you created a note manually or its frontmatter looks out of order, run Draftist: Normalize frontmatter. It sorts all properties into a consistent order and adds any missing fields.
The plugin also stores internal metadata in fields prefixed with [draftist]. These are hidden by default — you'll only see them if you enable "Expose internal metadata" in the plugin's debugging settings. Don't edit them manually — changing these values can corrupt the plugin's metadata state and cause publishing issues.
Publishing
When you're ready, run Draftist: Preview and publish command. The plugin saves a draft version of your page and opens it in your browser on your site's preview domain. Use the toolbar in that preview to publish the page or manage its availability.
If you use other third-party Obsidian plugins, the Obsidian team recommends using your primary browser for sensitive tasks and websites that require login instead of the web viewer for security reasons.
During publishing, the plugin adds block ID markers (like ^a1b2c3) to every block in your page. We know they can be a bit noisy, but they power useful features: readers and other pages can link directly to a specific paragraph or heading, they enable automatic table of contents generation, and the server can diff changes between versions to show exactly what was updated. You can adjust their opacity or disable them entirely in the plugin settings — though we recommend keeping them on.
Parent pages must be published before their children — the plugin will let you know if you try to publish a child whose parent isn't live yet. We'll make this one easier in the future.
If the page links to content that is not published, Draftist warns you before publishing. You can publish anyway, but those links will be broken until the linked content is published.
When unpublishing, archiving, or deleting a page, Draftist warns you if live content links to it or if child pages will also become unavailable.
After publishing or changing availability, when you return to the note, the plugin pulls the page's status and publication date back from your site. If Draftist reports that the page no longer exists, the plugin removes local Draftist metadata and image metadata sidecars, keeps status: Deleted, and leaves the note in place.