Skip to main content

Contributing to the Docs

This page covers how to add a blog post, edit existing documentation, and rebuild the docs site.

Prerequisites​

cd docs-site
npm ci      # install from package-lock.json — do this once

Node ≥ 20 is required (check with node --version).

Run the dev server​

cd docs-site
npm start

Opens http://localhost:3000/guide/ with hot reload. Changes to any .md file in docs/ or blog/ are reflected immediately in the browser.

Editing docs pages​

Documentation pages live in docs-site/docs/, organised into four folders:

docs/
├── getting-started/
├── user-guide/
├── tutorials/
└── reference/

Each .md file is a page. Edit it, save, and the dev server picks it up instantly.

Adding a new page​

  1. Create docs-site/docs/<section>/my-new-page.md
  2. Add frontmatter at the top: 
    ---
    sidebar_position: 6
    ---

    # My New Page
  3. Add the page ID to sidebars.ts under the appropriate category: 
    'reference/my-new-page',
  4. Run npm run build to verify no broken links.

Adding a blog post​

Blog posts live in docs-site/blog/. Each post is either a single .md file or a folder (for posts with images).

Create the post file​

Use the date-based naming convention Docusaurus expects:

blog/
└── 2026-06-15-my-post-slug/
    ├── index.md        ← post content
    └── screenshot.png  ← optional images

Or a single file for posts without assets:

blog/2026-06-15-my-post-slug.md

Write the frontmatter​

---
slug: my-post-slug
title: "A Descriptive Title"
authors: [epifanio]
tags: [announcement, grass-gis]
---

Opening paragraph — this appears on the blog list page as the excerpt.

{/* truncate */}

Full post content continues here...

Available tags (defined in blog/tags.yml):

Tag keyLabel
announcementAnnouncement
grass-gisGRASS GIS
web-gisWeb GIS
tutorialTutorial

Add new tags to blog/tags.yml if you need them.

:::note MDX syntax The docs site runs with future: { v4: true }, which treats all .md files as MDX. Use {/* truncate */} for the excerpt break — not <!-- truncate --> (HTML comments are not valid MDX). :::

Preview the post​

npm start

Navigate to http://localhost:3000/guide/blog.

Build and verify​

Always build before committing to catch broken links:

cd docs-site
npm run build

A successful build prints:

[SUCCESS] Generated static files in "build".

The build/ directory is gitignored. It must be present for FastAPI to serve the docs at /guide/ — rebuild it before each Docker image build.

Deploy​

After building, redeploy the FastAPI app so the new docs are served. See Deployment for the full steps.

In short:

# Build docs
cd docs-site && npm run build && cd ..

# Rebuild and push the Docker image
docker build -t your-registry/fastgis:latest .
docker push your-registry/fastgis:latest

# Redeploy the stack
docker stack deploy -c fastgis.yml fastgis