Deploying as a Static Website

You can deploy your documentation portal as a static website.

Gramax CLI is used for generating static websites based on content created in Gramax.

Prerequisites

• Node.js version 18 or higher (required for CLI).

• A text editor, such as Visual Studio Code.

• A terminal.

Quick Start

1. Install Gramax CLI: npm install -g gramax-cli.

2. Generate the static site: gramax-cli build --source ./content --destination ./output.

Detailed Steps

Step 1: Install Gramax CLI

Gramax CLI can be used in two ways:

1. Without installation: Run commands using npx: npx gramax-cli <command> [options].

2. Global installation: For frequent use, install it globally: npm install -g gramax-cli.

After installation, CLI commands are available from any directory.

Step 2. Generate the static site

To generate the site, run the following command: gramax-cli build [options].

Build options

Configure additional settings

You can configure additional site settings, including indexing, metrics collection, custom styles, and the catalog logo.

1. Use gramax.config.yaml. Create a file in the content root, add the required settings:

   build:
   	logo:
   		imageUrl: "https://example.com/logo.png" # See "Portal logo"
   		linkUrl: "https://example.com"
   
   	metrics: # See "Metrics collection"
   		yandex:
   			metricCounter: 12345678
   		matomo:
   			matomoSiteId: 1
   			matomoUrl: "https://example.com/matomo"
   			matomoContainerUrl: "https://example.com/container"
   
   	forceUiLangSync: true # Match the UI language to the content language
   
   	features: # Enable experimental features
   		- filtered-catalog # Filter the catalog by content
   		- export-pdf # Use the new PDF export

2. Use environment variables.

   Linux/macOS (bash/zsh)

   Windows (PowerShell)

   # Logo
   export LOGO_IMAGE_URL="https://example.com/logo.png"
   export LOGO_LINK_URL="https://example.com"
   
   # Metrics
   # Yandex Metrica
   export YANDEX_METRIC_COUNTER=12345678
   
   # Matomo site
   export MATOMO_SITE_ID=1
   export MATOMO_URL="https://example.com/matomo"
   
   # Optional container
   # export MATOMO_CONTAINER_URL="/container"                    # Relative path when MATOMO_URL is set
   # export MATOMO_CONTAINER_URL="https://example.com/container" # Absolute URL when MATOMO_URL is not set
   
   # UI language sync
   export FORCE_UI_LANG_SYNC=true
   
   # Experimental features
   export FEATURES="filtered-catalog,export-pdf"
   
   # Build the site
   gramax-cli build

   # Logo
   $env:LOGO_IMAGE_URL = "https://example.com/logo.png"
   $env:LOGO_LINK_URL = "https://example.com"
   
   # Metrics
   # Yandex Metrica
   $env:YANDEX_METRIC_COUNTER = "12345678"
   
   # Matomo site
   $env:MATOMO_SITE_ID = "1"
   $env:MATOMO_URL = "https://example.com/matomo"
   
   # Optional container
   # $env:MATOMO_CONTAINER_URL = "/container"                    # Relative path when MATOMO_URL is set
   # $env:MATOMO_CONTAINER_URL = "https://example.com/container" # Absolute URL when MATOMO_URL is not set
   
   # UI language sync
   $env:FORCE_UI_LANG_SYNC = "true"
   
   # Experimental features
   $env:FEATURES = "filtered-catalog,export-pdf"
   
   # Build the site
   gramax-cli build

3. CLI flags (equivalents).

   • forceUiLangSync → --force-ui-lang-sync (-l)
     When enabled, the user interface language is automatically aligned with the language of the selected content (if a UI translation is available). Example:

     gramax-cli build -l

   • features → --features (-f)
     Enables experimental features, listed as a comma‑separated string. Supported features:

     • filtered-catalog — catalog filtering by content;

     • export-pdf — new PDF export.

     Example:

     gramax-cli build -f "filtered-catalog,export-pdf"

Display diagrams on a static site

If the static site must display Draw.io and PlantUML diagrams, connect the diagram service before building the site.

1. Define the static site URL. Example: https://example.org.

2. Deploy the diagram service on your own server and add the static site URL to ALLOWED_GRAMAX_URLS for diagram-renderer.

   version: "3.8"
   
   services:
     diagram-renderer:
       image: docker.io/gramax/diagram-renderer:latest
       container_name: diagram-renderer
       restart: unless-stopped
       environment:
         - ALLOWED_GRAMAX_URLS=${ALLOWED_GRAMAX_URLS:-https://example.org}

3. Set DIAGRAM_RENDERER_SERVICE_URL before building. The value must match the URL where diagram-renderer is available.

   Linux/macOS (bash/zsh)

   Windows (PowerShell)

   export DIAGRAM_RENDERER_SERVICE_URL="https://services.example.org/diagram-renderer"

   $env:DIAGRAM_RENDERER_SERVICE_URL = "https://services.example.org/diagram-renderer"

4. Build the static site.

   gramax-cli build

5. Publish the generated files on the server.

Deploy to a subdirectory

After the build is complete, you can publish the static site either at the host root or in any subdirectory, depending on the target URL.

Examples:

• Host root: https://example.org/

• Subdirectory: https://example.org/docs/

Upload the generated files to the target directory on the server, for example /docs/.

Gramax CLI generates relative paths, so the site works correctly from any subdirectory without requiring changes to links or project structure.

Configure 404 page handling

If the site is hosted in a subdirectory, the 404 page must use the correct base path.

For example, if the site is hosted at https://example.org/docs/, the page https://example.org/docs/non-existent-page should open the custom 404.html page correctly.

One option is to do this manually: in the 404.html file, replace <base href="/"> with <base href="/docs/">.

Configure Nginx

Instead of editing the file manually, you can configure the web server to replace base href automatically when serving the 404 page.

Example Nginx configuration for a site hosted in the /docs/ subdirectory:

location /docs/ {
	try_files {%formula content="$uri $" /%}uri/ =404;
	error_page 404 /docs/404.html;
}

location = /docs/404.html {
	# Replace base href so that static assets load correctly
	sub_filter '<base href="/">' '<base href="/docs/">';
	sub_filter_once on;
	internal;
}