Getting Started with Syntax Scribe

Welcome to Syntax Scribe, a powerful tool for automatically generating beautiful code documentation from your TypeScript and JavaScript projects. This guide will walk you through installation, basic usage, and creating your first documentation site.

What is Syntax Scribe?

Syntax Scribe analyzes your TypeScript and JavaScript codebases to automatically generate comprehensive documentation. It integrates seamlessly with MkDocs to create professional documentation sites with minimal configuration.

Key Features: - Automatic code analysis and documentation generation - MkDocs integration with Material theme - Support for TypeScript and JavaScript projects - Built-in navigation generation - Local development server - Static site generation for easy deployment

Installation

Install Syntax Scribe globally using npm:

npm install -g syntax-scribe

System Requirements: - Node.js 14+ - npm or yarn package manager - Git (for project analysis)

Quick Start

Generate Documentation

Generate documentation from your project source code:

# Generate markdown documentation
syntax-scribe docs document -sourceDirectory "~/code/my-project" -docDirectory "~/code/my-docs"

# Generate markdown documentation & create MkDocs site with site name 'My MkDocs Site' and run it in a docker container
syntax-scribe docs document -sourceDirectory "~/code/my-project" -docDirectory "~/code/my-docs" --prepareMkdocs --siteName "My MkDocs Site" --dockerMkDocs

# Generate markdown documentation & create MkDocs site with site name 'My MkDocs Site' and run it locally (requires python)
syntax-scribe docs document -sourceDirectory "~/code/my-project" -docDirectory "~/code/my-docs" --prepareMkdocs --siteName "My MkDocs Site" --serveMkDocsSite

Command Options: - -s, --sourceDirectory: Path to your source code directory - -d, --docDirectory: Path where documentation will be generated - -l, --licenseKey: Your Syntax Scribe license key (optional) - -n, --saveAnalysis : saves analysis in file specified (license key required) - -f, --formatIndexForMkdocs: format index.md for use with MkDocs material - -m, --prepareMkdocs: Prepares a mkdocs.yml file in the docDirectory with basic configuration for MkDocs Material - -k, --dockerMkDocs: Serve site in Docker based MkDocs site - --serveMkDocsSite: Serve site locally in MkDocs site (Requires Python) - -j, --useJsDocs: Enable JSDoc-based documentation generation - --siteName: The MkDocs Site Name to be used in mkdocs.yml (Should be used in conjunction with --prepareMkDocs and/or --dockerMkDocs) - --omit : Sections to omit from the created documentation. Available: classes, functions, imports, variables, decorators, reExports, asyncPatterns, jsxElements, vueComposition, interfaces, typeAliases, enums - --buildMkDocsSite Builds the MkDocs site for deployment

What happens behind the scenes:

Running MkDocs Site Locally

• Generates a mkdocs.yml file for MkDocs
• Serves the MkDocs site in a Docker container

Running MkDocs Site Locally

• Creates a .venv Python virtual environment in your project directory
• Installs MkDocs, Material theme, and required plugins in the virtual environment
• Uses MkDocs to serve your site locally

Your site will be available at http://localhost:8000 with live reloading for development.

Running the site independently: If you want to run your documentation site again without using Syntax Scribe, you can use MkDocs directly:

# Navigate to your documentation project directory
cd ~/code/my-docs

# Activate the virtual environment
source .venv/bin/activate

# Run MkDocs serve
mkdocs serve

To deactivate the virtual environment when you're done, simply run:

deactivate

Step 2: Build MkDocs site for Production

Generate static files ready for deployment:

syntax-scribe docs build -d "~/code/my-docs" 

The built site will be created in the site/ directory, ready for hosting.

You can also build using MkDocs directly after activating the virtual environment:

source .venv/bin/activate
mkdocs build

Project Structure

After running the initialization commands, your project structure will look like this:

copilotkit-docs/
├── mkdocs.yml           # MkDocs configuration
├── .venv/               # Python virtual environment (created after first serve)
├── docs/                # Generated documentation
│   ├── index.md         # Homepage
│   ├── api/             # API documentation
│   └── guides/          # Additional guides
└── site/                # Built static site (after build)

Directory Path Tips

Important considerations for directory paths:

• Source directory (-s): Point to your project's root or main source directory
• Destination directory (-d):
• Use absolute paths or proper relative paths to avoid confusion
• Avoid spaces in directory names for better cross-platform compatibility

Example directory structure:

~/code/
├── my-project/          # Your source code (use for -s)
└── my-project-docs/     # Documentation project
    ├── mkdocs.yml       # Use parent directory for init (-d)
    ├── .venv/           # Virtual environment (auto-created)
    └── docs/            # Generated docs go here

Deployment Options

Your built documentation site consists of static files that can be hosted anywhere:

GitHub Pages

Follow our GitHub Pages deployment guide for step-by-step instructions.

Other Hosting Options

• Netlify: Drag and drop the site/ folder
• Vercel: Connect your repository for automatic deployments
• AWS S3: Upload static files to an S3 bucket
• Traditional web hosting: Upload site/ contents via FTP

For detailed deployment instructions, see the MkDocs deployment documentation.

Troubleshooting

Common Issues:

"Command not found" error - Ensure Syntax Scribe is installed globally: npm install -g syntax-scribe - Check your PATH includes npm global binaries

Documentation not generating correctly - Verify your source path points to a valid TypeScript/JavaScript project - Ensure the destination directory exists or can be created - Check file permissions for the destination directory

Local server not starting - Ensure port 8000 is available (or specify different port) - Check that mkdocs.yml exists in the specified directory - If running MkDocs directly, make sure the virtual environment is activated

Virtual environment issues - If .venv directory is missing, re-run syntax-scribe docs serve to recreate it - On Windows, use .venv\Scripts\activate instead of source .venv/bin/activate - Ensure Python 3.6+ is installed on your system

Next Steps

Once you have your basic documentation site running:

1. Customize your content - Edit the generated markdown files in your docs/ directory
2. Configure your theme - Modify mkdocs.yml to customize colors, fonts, and layout
3. Add custom pages - Create additional guides, tutorials, or reference materials
4. Set up automated deployment - Use GitHub Actions or other CI/CD tools for automatic updates

Additional Resources

MkDocs Documentation: - MkDocs Getting Started Guide - MkDocs User Guide - MkDocs Developer Guide

Material Theme: - Material for MkDocs Documentation - Material Theme Configuration

Syntax Scribe Resources: - Advanced Configuration Options

---

Need help? Check our troubleshooting section above or reach out to our support team with any questions about getting started with Syntax Scribe.