Setting up an authoring environment

This guide sets up a productive local environment for writing docs with Netdocs: an editor, the netdocs CLI on your PATH, and a live-preview workflow. It's aimed at content authors — if you want to hack on Netdocs itself, see Installation → From source.

1. Install an editor

Any editor works, but Visual Studio Code is a good default for Markdown:

• Markdown All in One — shortcuts, TOC, list editing.
• markdownlint — catches malformed Markdown as you type.
• Even Better TOML / YAML and a JSON language mode — for editing appsettings.json.
• Mermaid preview (optional) — preview diagrams without a full build.

Enable Format on Save and Trim Trailing Whitespace so pages stay tidy.

2. Install the netdocs CLI

Grab a prebuilt binary for your platform (no .NET runtime required). See Installation for all options; the short version:

curl -LO https://github.com/XtremeOwnage/Netdocs/releases/latest/download/netdocs_amd64.deb
sudo apt install ./netdocs_amd64.deb
netdocs --help

sudo yum install https://github.com/XtremeOwnage/Netdocs/releases/latest/download/netdocs_x86_64.rpm
netdocs --help

chmod +x netdocs
sudo mv netdocs /usr/local/bin/
netdocs --help

Put it on your PATH

Being able to type netdocs from any directory makes the workflow below smoother.

# Add the folder containing netdocs.exe to your user PATH (persists across sessions)
$dir = "C:\tools\netdocs"
[Environment]::SetEnvironmentVariable(
  "Path", "$([Environment]::GetEnvironmentVariable('Path','User'));$dir", "User")
# Open a new terminal, then:
netdocs --help

# If you moved the binary to /usr/local/bin it's already on PATH.
# Otherwise add its folder in your shell profile:
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.profile
source ~/.profile
netdocs --help

3. Get the docs project

Clone (or open) the repository that contains your docs/ folder and appsettings.json:

git clone https://github.com/your-org/your-docs.git
cd your-docs

If you're coming from MkDocs and only have a mkdocs.yml, convert it first:

netdocs import mkdocs.yml --out appsettings.json

See Migrating from MkDocs.

4. The live-preview loop

Run the dev server. It builds the site, serves it locally, watches your files, and reloads the browser on every save:

netdocs serve --config appsettings.json

Open http://localhost:8000 and start editing. Each save triggers an incremental rebuild and a live-reload over a WebSocket, so the page refreshes on its own.

Handy flags (full list in the CLI reference):

5. Before you commit

• Run a strict production build to catch errors your dev loop might tolerate:

  netdocs build --prod --strict --clean --config appsettings.json
  

• Review the rendered page(s) you changed — don't assume "it parsed" means "it looks right".

• Keep commits small and focused; the publishing guide covers deploying.

Troubleshooting