Building Your Site

Building your Mordoc documentation site compiles your markdown content into optimized static HTML files ready for deployment.

Build Command

Build your documentation site:

npm run build

This command:

1. Processes all markdown files
2. Generates HTML pages
3. Compiles and minifies CSS/JavaScript
4. Optimizes images
5. Creates search index
6. Outputs to dist/ directory

Build Output

$ npm run build

> mordoc build

✓ Processing markdown files...
✓ Generating pages...
✓ Building search index...
✓ Optimizing assets...
✓ Build complete!

Output: dist/
Pages: 24
Build time: 2.4s

Output Directory

The build generates a dist/ directory containing your complete static site:

dist/
├── index.html
├── get-started/
│   ├── index.html
│   └── creating-project/
│       └── index.html
├── assets/
│   ├── styles.css
│   ├── main.js
│   └── fonts/
├── images/
├── icons/
├── pagefind/           # Search index
│   ├── pagefind.js
│   └── ...
└── config.json

What Gets Built

Build Options

Specify Output Directory

npm run build -- --outDir=build

Clean Build

Remove previous build and create fresh:

npm run build -- --clean

Production Build

Optimize for production (default):

npm run build -- --mode=production

Development Build

Faster build without optimizations:

npm run build -- --mode=development

Verbose Output

Show detailed build information:

npm run build -- --verbose

Build Process

1. Content Processing

• Reads all markdown files from content/
• Parses frontmatter metadata
• Converts markdown to HTML
• Processes custom components (cards, callouts, etc.)

2. Page Generation

• Creates HTML pages for each markdown file
• Applies templates and layouts
• Injects navigation and TOC
• Generates breadcrumbs

3. Asset Optimization

• CSS: Minifies and combines stylesheets
• JavaScript: Bundles and minifies scripts
• Images: Copies and optionally optimizes
• Fonts: Includes referenced fonts

4. Search Index

• Scans all generated HTML
• Creates searchable index
• Generates Pagefind files
• Excludes configured content

5. Final Steps

• Copies public assets
• Generates sitemap.xml
• Creates 404 page
• Writes config.json

Build Configuration

Configure build behavior in config/site.json:

{
  "build": {
    "outDir": "dist",
    "cleanBuild": true,
    "minify": true,
    "sourcemaps": false,
    "generateSitemap": true
  }
}

Build Properties

Performance Optimization

Asset Optimization

Enable minification:

{
  "build": {
    "minify": true
  }
}

Optimize images:

{
  "build": {
    "optimizeImages": true,
    "imageQuality": 85
  }
}

Code Splitting

Large sites benefit from code splitting:

{
  "build": {
    "codeSplitting": true,
    "chunkSize": 100
  }
}

Lazy Loading

Enable lazy loading for images:

{
  "build": {
    "lazyLoadImages": true
  }
}

Build Size Analysis

Analyze build output size:

npm run build -- --analyze

Output:

Build Size Analysis
===================
HTML: 245 KB
CSS: 42 KB
JavaScript: 98 KB
Images: 1.2 MB
Fonts: 180 KB
Search Index: 156 KB
-------------------
Total: 1.92 MB

Deployment Preparation

Pre-Deployment Checklist

• [ ] All content is finalized
• [ ] Links are tested and working
• [ ] Images are optimized
• [ ] Configuration is correct
• [ ] Build completes without errors
• [ ] Site works locally with preview

Sitemap Generation

Sitemap is auto-generated if enabled:

<!-- dist/sitemap.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://docs.example.com/</loc>
    <lastmod>2024-01-15</lastmod>
  </url>
  <url>
    <loc>https://docs.example.com/get-started/creating-project</loc>
    <lastmod>2024-01-15</lastmod>
  </url>
</urlset>

Configure in config/site.json:

{
  "baseUrl": "https://docs.example.com",
  "build": {
    "generateSitemap": true
  }
}

Robots.txt

Create public/robots.txt:

User-agent: *
Allow: /
Sitemap: https://docs.example.com/sitemap.xml

This file is automatically copied to dist/.

Build Scripts

Custom Build Script

Add to package.json:

{
  "scripts": {
    "build": "mordoc build",
    "build:prod": "mordoc build --mode=production --clean",
    "build:analyze": "mordoc build --analyze"
  }
}

Pre/Post Build Hooks

Run scripts before/after build:

{
  "scripts": {
    "prebuild": "node scripts/prebuild.js",
    "build": "mordoc build",
    "postbuild": "node scripts/postbuild.js"
  }
}

Common Build Issues

Build Fails

Check for:

• Syntax errors in markdown files
• Invalid frontmatter YAML
• Missing files referenced in content
• Incorrect paths in sidenav.yaml
• Configuration JSON syntax errors

Debug:

npm run build -- --verbose

Out of Memory

For large sites:

NODE_OPTIONS=--max-old-space-size=4096 npm run build

Or in package.json:

{
  "scripts": {
    "build": "NODE_OPTIONS=--max-old-space-size=4096 mordoc build"
  }
}

Slow Build Times

Optimize:

• Reduce image sizes
• Limit markdown file size
• Disable unused features
• Use development build for testing

Assets Not Copied

• Verify files are in public/ directory
• Check file paths in markdown
• Ensure proper file permissions
• Rebuild with --clean flag

Build for Different Environments

Staging Build

{
  "scripts": {
    "build:staging": "mordoc build --env=staging"
  }
}

config/site.staging.json:

{
  "baseUrl": "https://staging.docs.example.com",
  "noindex": true
}

Production Build

{
  "scripts": {
    "build:prod": "mordoc build --env=production"
  }
}

Continuous Integration

GitHub Actions

.github/workflows/build.yml:

name: Build Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build site
        run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

GitLab CI

.gitlab-ci.yml:

build:
  image: node:18
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
  only:
    - main

Best Practices

Build Performance

1. Incremental builds: Use caching in CI/CD
2. Parallel processing: Enable if supported
3. Optimize assets: Compress images before committing
4. Clean selectively: Only when necessary

Build Verification

After building:

1. Check build output for errors
2. Verify all pages generated
3. Test search functionality
4. Check asset paths
5. Validate HTML (optional)

Version Control

.gitignore:

node_modules/
dist/
.DS_Store
*.log

Commit source files, not build output.

Next Steps

After building:

1. Preview - Test the build locally
2. Version Control - Commit your changes
3. Launch - Deploy to production