How to Generate and Serve Documentation

This guide explains how to install mdbook, integrate with JotDown, and generate NotionAiAssistant documentation locally.

Installing mdbook

mdbook is a tool written in Rust that generates beautiful books from Markdown files.

Installing via Cargo (Rust Package Manager)

If you already have Rust and Cargo installed:

cargo install mdbook

Installing via Precompiled Binaries

Alternatively, you can download precompiled binaries from the mdbook releases page.

Verifying the Installation

To verify that mdbook was installed correctly:

mdbook --version

JotDown Integration

For a seamless workflow between Notion and our MDBook documentation, we use JotDown:

Setting Up JotDown

  1. Install JotDown from the repository:

    git clone https://github.com/Harry-027/JotDown
cd JotDown
cargo build --release

  2. Configure your Notion API token:

    export NOTION_TOKEN="your_notion_integration_token"

  3. Run JotDown to sync content from Notion to your documentation folder:

    ./target/release/JotDown

Automated Documentation Workflow

Our workflow combines Notion, JotDown, and MDBook:

  1. Write and organize content in Notion
  2. Use JotDown to convert Notion pages to Markdown files
  3. JotDown automatically organizes the content in your MDBook structure
  4. Generate the final documentation with mdbook

Generating the Documentation

Building the Book

To generate the static HTML files:

cd /path/to/NotionAiAssistant/docs
mdbook build

The files will be generated in the book/ folder inside the docs/ directory.

Serve Locally

To start a local server that updates automatically when files are changed:

cd /path/to/NotionAiAssistant/docs
mdbook serve

This will start a local web server, usually on port 3000. You can access the documentation at:

http://localhost:3000

Additional Options

  • To specify a different port:
mdbook serve --port 8000
  • To build and serve without automatically opening the browser:
mdbook serve --open false

Updating the Documentation

  1. Update content in Notion
  2. Run JotDown to sync changes to your local Markdown files
  3. If you are using mdbook serve, the changes will be reflected automatically
  4. If you are using mdbook build, run the command again to regenerate the files

File Structure

  • SUMMARY.md: Define the structure of the book and summary
  • book.toml: Configuration of mdbook
  • Other .md files: Documentation content

Contributing Tips

  • Keep formatting consistent
  • Use web-optimized images
  • Test the documentation locally before committing
  • Keep the navigation logical in the SUMMARY.md file
  • Use Notion for collaborative content creation, then sync with JotDown

Troubleshooting

Common Problems

  1. "Command not found" error:

    • Make sure mdbook is installed and in your PATH

  2. Build error:

    • Check links to images and other resources
    • Check for Markdown syntax errors

  3. Images not showing up:

    • Check the relative paths to image references

  4. JotDown sync issues:

    • Verify your Notion API token is correct
    • Ensure you have proper permissions in Notion
    • Check if Notion API rate limits are affecting your sync

For more help, see the official mdbook documentation and the JotDown repository.