Note Site Builder

Note Site Builder

Turn an Obsidian note, or a whole folder of notes, into a clean website and matching PDFs: a handout, a course page, a lab manual, a report. Write in Obsidian as usual; the plugin does the typesetting.

• Numbered sections and a contents rail that follows you as you scroll.
• Numbered figures with captions, straight from your image embeds.
• Excalidraw drawings as crisp SVG figures.
• A Websites panel listing every site in your vault, one click from building, previewing and publishing.
• Maths with KaTeX, $inline$ and $$display$$.
• A print-ready PDF, A4 or Letter: each section starts a new page, with a running head and page numbers.
• Several pages from a folder, with a bar linking them and working [[links]] between pages.
• Live preview in your browser that reloads every time you save.
• Publish with git, one click: commit and push the note and its site, for example to GitHub Pages.

Set up a website in one step

Right-click a folder and choose Set up website… (or run Set up a new website…). One dialog asks:

• One page or several. One page makes a single note into a page. Several pages makes every note in the folder a page.
• Which note is the home page: an existing one or a new one it creates.
• Title, the line above it and a subtitle for the masthead.
• Where the built site goes (default site/ inside the folder).
• Whether to put it online with GitHub Pages. If so, it creates a git repository if the folder isn't in one, connects GitHub, adds the Pages workflow and, if you like, publishes straight away. With the GitHub CLI signed in, it can create the GitHub repository and switch Pages on for you. Without it, you paste the address of an empty repository and switch Pages on once in its settings.

Running it again on the same folder updates the settings instead of starting over.

All your websites in one place

Click the globe in the ribbon and choose Show all websites, or run the command of that name. A panel opens listing every website in the vault: each multi-page site, and every note that has been built or has a site-folder:. Each entry shows its pages, where it builds to, when it was last built, its GitHub Pages address, and buttons to build, build with PDF, preview, open, publish, and change its settings.

Use

Open a note, then click the globe in the left ribbon, or run a command from the command palette:

You can also right-click a note in the file explorer and choose Build website.

By default a note's site goes into a folder next to it, named after the note (My Handout.md → my-handout-site/). Change the pattern in settings, or give one note its own folder with a site-folder: property.

Writing for the page

The note's top-level headings become the numbered sections. The contents rail lists them, along with the headings one level below. A note whose headings start at ## works too. Anything before the first heading opens the page without a number.

Figures. An image embed on its own line becomes a numbered figure. The caption is the next line if that line is entirely italic or bold:

![[confocal.png|400]]
*Maximum projection of a 5 dpf larva. Scale bar 50 µm.*

|400 sets the display width, as in Obsidian. Other text after the pipe is used as the caption. A typed "Figure 3." prefix is dropped, because numbering is automatic.

Excalidraw drawings embed like images: ![[My diagram.excalidraw|500]] with a caption line under it becomes a numbered figure. The drawing is exported as SVG in the light theme when you build, so the Excalidraw plugin needs to be on. Without it, an SVG or PNG that Excalidraw auto-exported next to the drawing is used instead.

The masthead comes from optional properties:

---
title: The cerebellum in *inpp5e* mutants
eyebrow: BIO321 · Practical course 2026
subtitle: A whole-mount immunofluorescence project in larval zebrafish.
notice: "**Draft.** Some sections are still being written."
---

Without a title:, the page is named after the note.

Laser lines. /laser{488} shows a dot in the colour of the channel that line excites, followed by "488 nm", in tables or running text. 405, 488, 561 and 647 are blue, green, orange and far red; other wavelengths get a blend of their neighbours. The chips appear in Obsidian's reading view and live preview as well as on the page. Type /laser for a list of common lines.

Several pages. A folder is a multi-page site when one of its notes has site-home: true (the setup dialog adds it). That note becomes index.html; every other note in the folder and its subfolders becomes a page named after it, listed in the bar at the top. site-order: 2 sets a note's place in the bar, and site-hide: true leaves a note out. [[Other page]] and [[Other page#Heading]] link across pages; links to notes that aren't on the site become plain text. Any build or preview command run from any page builds the whole site.

Keeping things off the page without deleting them from the note:

• ## Experiment 3 //hidden: hides the heading and everything under it, down to the next heading of the same or higher level.
• 1) Why use projections? //answer Smaller files, faster analysis: hides the rest of the line after //answer, so questions go out without their answers. A line that starts with //answer is dropped entirely.
• %% comments %% are dropped, as in Obsidian's reading view.

Also supported: tables (wide ones scroll), callouts (> [!note], including nested ones), ==highlights==, task lists and code blocks. [[#Heading]] links jump within the page. Links to other notes become plain text, since only this note is published. A heading with nothing under it gets a "to be written" box; you can turn that off in settings.

Putting it online with GitHub Pages

1. Keep the note in a git repository with a GitHub remote.

2. On GitHub, open Settings → Pages and set Source to GitHub Actions.

3. Add .github/workflows/pages.yml, with path: set to your site folder:

   name: Pages
   on: { push: { branches: [main] } }
   permissions: { contents: read, pages: write, id-token: write }
   jobs:
     deploy:
       runs-on: ubuntu-latest
       environment: { name: github-pages }
       steps:
         - uses: actions/checkout@v4
         - uses: actions/upload-pages-artifact@v3
           with: { path: my-handout-site }
         - uses: actions/deploy-pages@v4
   

4. From then on, Publish with git is all it takes. It builds the page, commits and pushes.

Choosing what gets published. The note and its site are always included. The Publish dialog also lists the note's folder and each folder above it, up to the top of the repository, and Add another folder… takes any other folder in the repository. Tick the ones to include; the list of changed files updates as you go, so you can see exactly what will be pushed. Each note remembers its selection. Settings → Publish by default sets the starting point for notes without one: only the note and its site, its whole folder, or the whole repository.

Privacy and what the plugin touches

• It only writes inside the output folder you configure, in your vault.
• The live preview server listens on 127.0.0.1 only.
• The built page loads KaTeX from the jsDelivr CDN for maths. Nothing else is fetched, and the plugin itself makes no network requests.
• It runs git only when you use Publish, or to stamp the page with the commit it was built from, and only when the note is in a git repository.
• PDFs are printed by Obsidian's built-in Chromium. If that isn't available, an installed Chrome or Edge is used.

Desktop only.

Development

npm install
npm run dev      # rebuilds main.js on change
npm run build    # type-check and production build

Release: npm version patch && git push --follow-tags. The workflow attaches main.js, manifest.json and styles.css to a GitHub release.

License

MIT