Public Documents

This directory contains markdown documents that are automatically rendered to HTML and PDF formats for public access. These documents are typically legal or informational documents such as privacy policies, license terms, and terms of service.

Document Types

The following types of documents are typically transformed and offered publicly:

How documents are maintained

Within google docs, an overview is managed and contains links to:

If any of these documents is updated, it should be exported as markdown and updated here to. If a name of an document hereby did change, the affected jumplink must also be updated.

How It Works

Documents in this directory are processed by the renderMarkdown script, which:

  1. Converts Markdown to HTML and PDF - Each .md file is rendered to both HTML and PDF formats
  2. URL-Compatible Naming - File and directory names are automatically converted to be web-compatible:
    • Umlauts (ä, ö, ü, Ä, Ö, Ü) are replaced with URL-safe equivalents (ae, oe, ue, Ae, Oe, Ue)
    • Spaces are replaced with underscores
    • Special characters are normalized
  3. Index Generation - An index.html file is automatically generated with links to all rendered documents
  4. Output Location - Rendered files are placed in bin/public/documents/ for deployment

Building Documents

To build all documents, run:

npm run build:documentation

This command:

To clean the output directory:

npm run clean:documentation

Customization Options

The rendering script supports various customization options through command-line arguments or by modifying the script itself.

Command-Line Options

Output Format

Control which formats are generated:

# Generate both HTML and PDF (default)
node bin/scripts/renderMarkdown.js --input=public/documents --format=both

# Generate HTML only
node bin/scripts/renderMarkdown.js --input=public/documents --format=html

# Generate PDF only
node bin/scripts/renderMarkdown.js --input=public/documents --format=pdf

Custom CSS Styling

Provide a custom CSS file to override the default styling:

node bin/scripts/renderMarkdown.js --input=public/documents --cssPath=./custom-styles.css

The custom CSS will be applied to both HTML and PDF outputs. If not provided, a default stylesheet is used that includes:

Index File Customization

Control index generation and naming:

# Generate index with custom name
node bin/scripts/renderMarkdown.js --input=public/documents --generateIndex=true --indexFileName=documents.html

# Skip index generation
node bin/scripts/renderMarkdown.js --input=public/documents --generateIndex=false

Output Directory

Specify a custom output directory:

node bin/scripts/renderMarkdown.js --input=public/documents --outputDir=./output/docs

Markdown Features Supported

The renderer uses MarkdownIt with the following features enabled:

Supported Markdown Syntax

Customizing Default Styles

To customize the default CSS, you can:

  1. Create a custom CSS file and use the --cssPath option
  2. Modify the script - Edit src/scripts/renderMarkdown.ts and update the defaultCss constant (around line 115)

The default CSS includes:

PDF Customization

PDF generation uses Playwright’s Chromium browser. The PDF settings can be customized in the writePdfFromHtml function:

To modify PDF settings, edit src/scripts/renderMarkdown.ts around line 196.

File Naming Conventions

When adding new documents:

  1. Use descriptive names - Clear, descriptive filenames help identify document purpose
  2. Use underscores for spaces - While the script converts spaces automatically, using underscores in source files is recommended
  3. Avoid special characters - Stick to letters, numbers, underscores, and hyphens
  4. Use .md extension - Only .md files are processed

Example good filenames:

Adding New Documents

To add a new public document:

  1. Create a new .md file in public/documents/
  2. Write your content using markdown syntax
  3. Run npm run build:documentation to generate HTML and PDF versions
  4. The document will automatically appear in the generated index.html

Technical Details

Troubleshooting

Documents Not Rendering

PDF Generation Issues

Styling Issues

Script Location

The rendering script is located at:

For more information about the script’s command-line interface, run:

node bin/scripts/renderMarkdown.js --help