Update documentation

gbro3n · gbro3n · commit 1823eef013ba · 2026-03-07T16:02:09.000Z
diff --git a/README_GITHUB_PAGES.md b/README_GITHUB_PAGES.md
@@ -0,0 +1,19 @@
+# GitHub Pages Setup
+
+## Overview
+
+The static site (generated from `docs-src/`) is deployed to GitHub Pages via the CI workflow on every push to `main`.
+
+## Custom Domain
+
+A custom domain is configured at the appsoftwareltd organisation level:
+
+1. **GitHub domain verification** — completed the DNS verification challenge in GitHub organisation settings before adding the custom domain.
+2. **DNS record** — added a `CNAME` record (non-proxied / DNS only) pointing the subdomain to `appsoftwareltd.github.io`.
+3. **HTTPS** — once GitHub verified the DNS record, HTTPS enforcement was enabled in repo Settings → Pages.
+
+## Notes
+
+- The `docs/` folder is wiped and regenerated on each CI run, so a `CNAME` file must be written by the CI workflow after conversion if a custom domain is used (see `build-docs` job in `.github/workflows/ci.yml`).
+- Using `<user/org>.github.io` is an option for repositories without custom domains, or under an org that has a custom domain configured at the org level — in which case GitHub applies the org domain automatically.
+- The GitHub Pages source is set to **GitHub Actions** in repo Settings → Pages.
diff --git a/docs-src/pages/Publishing a Static Site.md b/docs-src/pages/Publishing a Static Site.md
@@ -0,0 +1,104 @@
+# Publishing a Static Site
+
+AS Notes includes a built-in HTML conversion tool that turns your markdown notes into a static website. You can use this to publish your knowledge base as a standalone site or deploy it to GitHub Pages.
+
+## How It Works
+
+The `html-conversion` package scans a folder of markdown files and converts them to HTML. [[Wikilinks]] between pages are automatically resolved to the correct HTML links.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) 20 or later
+- Your notes in a folder of `.md` files
+
+## Standalone Usage
+
+### 1. Install the converter
+
+Clone or download the `html-conversion` package from the AS Notes repository, then install dependencies:
+
+```bash
+cd html-conversion
+npm install
+npm run build
+```
+
+### 2. Convert your notes
+
+```bash
+npm run convert -- --input /path/to/your/notes --output /path/to/output
+```
+
+The output folder will be wiped and regenerated on each run. Point any static file server at the output folder to preview the result.
+
+### Local preview
+
+You can serve the output locally using any static file server, for example:
+
+```bash
+npx serve /path/to/output
+```
+
+## Publishing to GitHub Pages
+
+### 1. Add a CI workflow
+
+Create `.github/workflows/pages.yml` in your repository:
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+        working-directory: html-conversion
+      - run: npm run build
+        working-directory: html-conversion
+      - run: npm run convert -- --input ../notes --output ../site
+        working-directory: html-conversion
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+Adjust the `--input` path to match the folder containing your notes.
+
+### 2. Enable GitHub Pages
+
+In your repository go to **Settings → Pages** and set the source to **GitHub Actions**.
+
+### Custom Domain
+
+If you want to serve from a custom domain (e.g. `docs.example.com`):
+
+1. Add a DNS `CNAME` record (non-proxied if using Cloudflare):
+   ```
+   docs.example.com  CNAME  <your-github-username>.github.io
+   ```
+2. Add a step to your workflow to write the `CNAME` file into the output folder (the converter wipes the output on each run, so this must be done after conversion):
+   ```yaml
+   - run: echo "docs.example.com" > ../site/CNAME
+     working-directory: html-conversion
+   ```
+3. Enter the domain in **Settings → Pages → Custom domain** and wait for DNS verification.
+4. Once verified, enable **Enforce HTTPS**.
+
+> **Note:** If your repository belongs to a GitHub organisation that has a custom domain configured at the org level, GitHub will apply that domain automatically to all repos. In that case you either configure a per-repo custom domain as above, or complete the org-level DNS setup to make the org domain work.
diff --git a/docs-src/pages/Wikilinks.md b/docs-src/pages/Wikilinks.md
@@ -0,0 +1,75 @@
+# Wikilinks
+
+Wikilinks are a way to link between notes using a simple double-bracket syntax. They are the core navigation primitive in AS Notes, popularised by tools like Roam Research, Logseq, and Obsidian.
+
+## Basic Syntax
+
+Wrap any page name in double square brackets to create a link:
+
+```
+[[Page Name]]
+```
+
+AS Notes resolves the link to the matching file anywhere in your workspace — you do not need to specify a folder path or file extension. If a file called `Page Name.md` exists anywhere in the workspace, the link will navigate to it.
+
+## How Resolution Works
+
+Links are resolved by page name only. Given a workspace with these files:
+
+```
+notes/
+  Project Ideas.md
+  journal/
+    2026_03_07.md
+```
+
+The link `[[Project Ideas]]` resolves correctly regardless of which file it appears in or how deeply nested the files are.
+
+## Nested Wikilinks
+
+AS Notes supports wikilinks nested inside other wikilinks. This allows page names to themselves reference other pages, making it possible to build composite page names that remain fully navigable.
+
+### Single nesting
+
+The outer link's page name includes the inner link text (brackets and all):
+
+```
+[[[[AS Notes]] Features]]
+```
+
+This creates two links:
+- `[[[[AS Notes]] Features]]` — links to a page named `[[AS Notes]] Features`
+- `[[AS Notes]]` — links to a page named `AS Notes`
+
+### Double nesting
+
+```
+[[[[[[Deep]] Nested]] Page]]
+```
+
+This resolves three links:
+- `[[[[[[Deep]] Nested]] Page]]` — links to `[[[[Deep]] Nested]] Page`
+- `[[[[Deep]] Nested]]` — links to `[[Deep]] Nested`
+- `[[Deep]]` — links to `Deep`
+
+### Practical use
+
+Nested wikilinks are useful when you have a topic hierarchy where sub-pages share their parent's name. For example, if you have a page called `AS Notes` and a page called `[[AS Notes]] Changelog`, you can write:
+
+```
+See the [[[[AS Notes]] Changelog]] for recent changes.
+```
+
+Both the parent and the composite page name remain independently navigable.
+
+## Backlinks
+
+AS Notes maintains a backlink index as you write. The **Backlinks Panel** (`Ctrl+Alt+B` / `Cmd+Alt+B`) shows every note that links to the currently open page, including links via nested wikilinks.
+
+## Rename Tracking
+
+When you rename a file, AS Notes automatically updates all wikilinks that reference that file across your entire workspace — including nested wikilinks where the renamed page appears as an inner component.
+
+## Missing Links
+
+A wikilink to a page that does not yet exist is still valid syntax. AS Notes will highlight it differently and you can navigate to it to create the page. This makes it easy to link-first and write later.
diff --git a/docs-src/pages/index.md b/docs-src/pages/index.md
@@ -4,6 +4,8 @@ This is the documentation for AS Notes. This documentation was written using AS
 
 To start, why not read all about [[Wikilinks]].
 
+Want to publish your own notes as a website? See [[Publishing a Static Site]].
+
 What if we wrote a page about [[Nested [[Wikilinks]]]]?
 
 What if we wrote a page about [[Missing [[Wikilinks]]]]?
