Step 1: Initialize a Publishing Project

Run the command Scimax: Initialize Publishing Project (scimax.publish.init) from the Command Palette to start the 5-step wizard:

1. Project name - A short identifier (e.g., "my-website")

2. Source directory - Where your org files are located (default: ./org)

3. Output directory - Where HTML files will be published (default: ./docs for GitHub Pages)

4. Publishing target - GitHub Pages (recommended) or Local/Custom

5. Sitemap generation - Whether to auto-generate an index page

Step 2: Add Content

Create or edit `.org' files in your source directory. Each file becomes an HTML page.

Example ./org/about.org:

#+TITLE: About This Project
#+AUTHOR: Your Name
#+DATE: 2026-01-16

* Introduction

Welcome to my project documentation!

* Features

- Feature one
- Feature two

Step 3: Publish

Run Scimax: Publish Project (scimax.publish.project) to generate HTML files, or run scimax publish from a terminal (see CLI: Publish).

Step 4: Deploy to GitHub Pages

1. Commit the ./docs folder to your repository

2. Go to your repository's Settings → Pages

3. Set Source to "Deploy from a branch"

4. Select main branch and /docs folder

5. Your site will be live at https:username.github.iorepo-name

✅ YAML Configuration (_config.yml)

For Jupyter Book compatibility, create a _config.yml in your project root:

# _config.yml - Jupyter Book compatible
title: "My Documentation"

publish:
  base_directory: "./docs"
  publishing_directory: "./public"
  recursive: true
  auto_sitemap: true
  sitemap_filename: "index.org"

html:
  use_default_theme: true
  toc_depth: 3
  css_files:
    - "./css/custom.css"

github_pages: true

A _config.yml defines a single project. Its name is the title lowercased, with spaces replaced by hyphens (title: "My Documentation" gives the project my-documentation; with no title it is default). Pass that name to scimax publish <project>.

Other keys read from _config.yml:

publish.* keys take precedence over the top-level aliases.

JSON Configuration (`.org-publish.json')

{
  "projects": {
    "website": {
      "baseDirectory": "./org",
      "publishingDirectory": "./docs",
      "recursive": true,
      "autoSitemap": true
    }
  },
  "githubPages": true
}

Full Configuration Reference

{
  "projects": {
    "my-website": {
      "baseDirectory": "./org",
      "baseExtension": "org",
      "publishingDirectory": "./docs",
      "recursive": true,

      "exclude": "drafts/*",
      "include": ["extra/special.org"],

      "publishingFunction": "org-html-publish-to-html",

      "autoSitemap": true,
      "sitemapFilename": "index.org",
      "sitemapTitle": "Home",
      "sitemapStyle": "list",
      "sitemapSortFiles": "alphabetically",
      "sitemapSortFolders": "first",

      "htmlPreamble": "./templates/nav.html",
      "htmlPostamble": "./templates/footer.html",
      "htmlHead": "<meta name=\"keywords\" content=\"org-mode, documentation\">",
      "htmlHeadExtra": "<link rel=\"icon\" href=\"/favicon.ico\">",
      "cssFiles": ["./css/style.css"],
      "jsFiles": ["./js/custom.js"],
      "useDefaultTheme": true,

      "withAuthor": true,
      "withCreator": true,
      "withToc": true,
      "sectionNumbers": false,
      "defaultTitle": "Untitled"
    }
  },
  "githubPages": true,
  "customDomain": "docs.example.com",
  "defaultProject": "my-website"
}

File Selection Options

Publishing Function Options

Available functions:

• `org-html-publish-to-html' - Convert org files to HTML

• `md-html-publish-to-html' - Convert Markdown files to HTML

• `ipynb-html-publish-to-html' - Convert Jupyter notebooks to HTML

• `auto' - Auto-detect by file extension (default behavior)

• `copy' - Copy files as-is (for static assets)

Supported File Types

The publishing system supports multiple file types:

When using `auto' or `org-html-publish-to-html', files are processed based on their extension.

Sitemap Options

Sort options for sitemapSortFiles:

• `alphabetically' - Sort A-Z by title

• chronologically - Oldest first (by #+DATE)

• `anti-chronologically' - Newest first (for blogs)

HTML Template Options

Export Options

Global Options

Component Projects

A component project groups multiple projects together:

{
  "full-site": {
    "components": ["pages", "static", "images"]
  }
}

When you publish "full-site", all component projects are published in order.

Overview

When a _toc.yml file exists in your source directory, the publishing system:

1. Publishes files in the order specified (not alphabetically)

2. Generates prev/next navigation links on each page

3. Creates an index page reflecting the TOC structure

4. Only includes files listed in the TOC (plus unlisted if configured)

Basic _toc.yml Format

Create a _toc.yml file in your source directory (e.g., ./docs/_toc.yml):

# Simple flat structure
format: scimax
root: index

chapters:
  - file: getting-started
  - file: installation
  - file: configuration
  - file: advanced-usage

With Sections (Nested Chapters)

format: scimax
root: index

chapters:
  - file: getting-started
    sections:
      - file: getting-started/installation
      - file: getting-started/first-steps
  - file: user-guide
    sections:
      - file: user-guide/basics
      - file: user-guide/advanced
  - file: reference

With Parts (Book Format)

For larger documentation with multiple parts/volumes:

format: jb-book
root: intro

parts:
  - caption: Getting Started
    chapters:
      - file: installation
      - file: quickstart
      - file: tutorials

  - caption: User Guide
    chapters:
      - file: basics
        sections:
          - file: basics/syntax
          - file: basics/formatting
      - file: advanced

  - caption: Reference
    chapters:
      - file: api-reference
      - file: changelog

TOC Options

Entry Options

Custom Titles

You can override the title from the file's #+TITLE:

chapters:
  - file: api
    title: API Reference (Complete)
  - file: changelog
    title: Version History

External Links

Include external URLs in your TOC:

chapters:
  - file: documentation
  - url: https://github.com/user/repo
    title: Source Code
  - url: https://github.com/user/repo/issues
    title: Report Issues

Navigation Links

When using _toc.yml, each published page automatically gets:

<nav class="page-navigation">
  <a href="previous.html" class="nav-prev">← Previous</a>
  <a href="next.html" class="nav-next">Next →</a>
</nav>

You can style these with CSS:

.page-navigation {
  display: flex;
  justify-content: space-between;
  padding: 1rem 0;
  border-top: 1px solid #eee;
  margin-top: 2rem;
}
.nav-prev, .nav-next {
  color: #0066cc;
}

Combining with Configuration

Your .org-publish.json works the same way - the _toc.yml just controls ordering:

{
  "projects": {
    "docs": {
      "baseDirectory": "./docs",
      "publishingDirectory": "./public",
      "autoSitemap": true,
      "sitemapFilename": "index.org",
      "sitemapTitle": "Documentation"
    }
  }
}

With ./docs/_toc.yml:

format: scimax
root: intro
chapters:
  - file: getting-started
  - file: user-guide
  - file: reference

File Extension Resolution

The TOC references files without extensions. The system automatically finds files with these extensions (in order):

1. `.org'

2. `.md'

3. `.ipynb'

So file: getting-started will match getting-started.org, getting-started.md, or getting-started.ipynb.

HTML Preamble (Navigation)

Create a file like ./templates/nav.html:

<nav class="site-nav">
    <a href="index.html">Home</a>
    <a href="about.html">About</a>
    <a href="sitemap.html">Contents</a>
</nav>

Reference it in your config:

{
  "htmlPreamble": "./templates/nav.html"
}

HTML Postamble (Footer)

Create ./templates/footer.html:

<footer>
    <p>&copy; 2026 Your Name. Generated by scimax-vscode.</p>
</footer>

Custom CSS

Create ./css/style.css and reference it:

{
  "cssFiles": ["./css/style.css"]
}

Requirements

Theme publishing requires a _toc.yml in the source directory (see Explicit Table of Contents). Without it, publishing fails with Theme-based publishing requires a _toc.yml file.

A _static/ folder in the source directory is copied to the output, so put the logo and custom CSS there.

Theme Options

The defaults apply to every key you leave out, including keys missing from a section you do set: a header section with only a logo keeps the default title.

✅ Turning It On

The chat is off unless theme.chat.enabled is true in _config.yml:

theme:
  name: "book"
  chat:
    enabled: true

When it is on, publish:

• adds an "Ask" button in the bottom right corner of every page, in the site's primary_color (an icon-only circle on narrow screens)

• writes _static/chat-index.json, the text of every page split at its headings

• copies book-chat.js, book-chat-worker.js and book-chat.css to _static/

✅ How Questions Are Answered

1. The question is matched against the sections with BM25 ranking (headings count more than body text, pairs of adjacent words count as phrases, and a dotted name such as scimax.export.pdf.profile matches whole or in parts).

2. The best 30 are reranked by a small cross-encoder model (ms-marco-MiniLM-L-6-v2, about 23 MB, run in the browser with transformers.js) that reads the question and each section together. Its order is blended with the BM25 order, so neither one alone decides. If the reranker cannot load, the BM25 order is used.

3. The top sections, at most two from one page, are listed right away as links, each with the part of its text that matches the question highlighted.

4. A "Write an answer from these sections" button gives the numbered sections to the model, which answers from them and cites them as [1], [2]. Citations become links to the sections.

A short follow-up ("and for HTML?") is searched together with the question before it, and the last two questions and answers are given to the model.

The ranking model loads by itself the first time a reader asks. The first time a reader asks for a written answer, the chat asks before downloading the language model. The browser keeps both for later visits. In a browser without WebGPU, the chat lists the matching sections without the answer button.

✅ Choosing a Model

Readers pick the model from the menu at the top of the chat panel. The smallest is the default; larger ones answer better but take longer to download and need more GPU memory. The reader's choice is remembered in the browser.

The small models can be wrong, which is why the chat always shows the sections it used.

✅ Chat Options

The model IDs are those of WebLLM 0.2.85, which the chat loads from jsDelivr.

theme:
  chat:
    enabled: true
    model: "Llama-3.2-1B-Instruct-q4f16_1-MLC"
    models:
      - "Llama-3.2-1B-Instruct-q4f16_1-MLC"
      - "Qwen2.5-3B-Instruct-q4f16_1-MLC"
    top_k: 4

✅ Related Topics

• Database and Search - full-text and semantic search inside VS Code

• CLI: Publish - scimax publish from the command line

Custom Domain Setup

To use a custom domain:

{
  "githubPages": true,
  "customDomain": "docs.example.com"
}

Then configure your DNS to point to GitHub Pages.

Documentation Site

{
  "projects": {
    "docs": {
      "baseDirectory": "./docs-src",
      "publishingDirectory": "./docs",
      "autoSitemap": true,
      "sitemapFilename": "index.org",
      "sitemapTitle": "Documentation",
      "withToc": 2
    }
  },
  "githubPages": true
}

Blog

{
  "projects": {
    "blog": {
      "baseDirectory": "./posts",
      "publishingDirectory": "./docs",
      "autoSitemap": true,
      "sitemapFilename": "index.org",
      "sitemapTitle": "Blog",
      "sitemapSortFiles": "anti-chronologically",
      "htmlPreamble": "./templates/blog-header.html"
    }
  },
  "githubPages": true
}

Project with Static Assets

{
  "projects": {
    "pages": {
      "baseDirectory": "./org",
      "publishingDirectory": "./docs",
      "autoSitemap": true
    },
    "images": {
      "baseDirectory": "./images",
      "publishingDirectory": "./docs/images",
      "baseExtension": "png|jpg|gif|svg",
      "publishingFunction": "copy"
    },
    "css": {
      "baseDirectory": "./css",
      "publishingDirectory": "./docs/css",
      "baseExtension": "css",
      "publishingFunction": "copy"
    },
    "site": {
      "components": ["pages", "images", "css"]
    }
  },
  "githubPages": true,
  "defaultProject": "site"
}

"No publishing configuration found"

Run Scimax: Initialize Publishing Project (scimax.publish.init), or scimax publish --init from a terminal, to create a .org-publish.json file.

"Base directory does not exist"

Create the source directory specified in `baseDirectory', or update the config to point to an existing directory.

Links not working after publish

Ensure you're using file: links to reference other org files:

[[file:other.org][Link text]]

GitHub Pages not updating

1. Ensure the ./docs folder is committed

2. Check that GitHub Pages is configured to serve from /docs

3. Wait a few minutes for GitHub to rebuild the site