Quick start

This guide scaffolds a minimal Netdocs project and builds it.

1. Create the project layout

my-site/
├─ appsettings.json
└─ docs/
   └─ index.md

2. Write appsettings.json

Scaffold it instead

Run netdocs new to generate a fully-annotated appsettings.json with every common option, sane defaults, and links back to these docs — then edit to taste. See the netdocs new reference.

The site is configured under the Netdocs section:

{
  "Netdocs": {
    "siteName": "My Site",
    "siteUrl": "https://example.com/",
    "docsDir": "docs",
    "siteDir": "site",
    "theme": {
      "name": "material",
      "palette": [
        { "scheme": "default", "primary": "indigo", "accent": "indigo" }
      ],
      "features": [ "navigation.tabs", "content.code.copy" ]
    },
    "nav": [
      { "title": "Home", "path": "index.md" }
    ],
    "plugins": [
      { "name": "search" }
    ],
    "markdownExtensions": [
      { "name": "admonition" },
      { "name": "toc", "options": { "permalink": true } }
    ]
  }
}

See Configuration for the full schema.

3. Add content

# Welcome

This is my first **Netdocs** page.

!!! tip
    Admonitions, tabs, code highlighting, and search all work out of the box.

4. Build

cd my-site
netdocs build

The rendered site is written to site/. Open site/index.html in a browser, or serve it locally.

5. Serve with live reload

netdocs serve --port 8000

Netdocs starts a Kestrel dev server, watches the docs/ directory, and reloads the browser over a WebSocket whenever a file changes. It automatically picks a free port if the requested one is taken.

Set up a smoother authoring loop

See the Authoring environment guide for editor setup, putting netdocs on your PATH, and pre-commit checks.

Next steps