Skip to content

building-docs.md

Latest commit

 

History

History
96 lines (71 loc) · 3.38 KB

building-docs.md

File metadata and controls

96 lines (71 loc) · 3.38 KB

Documentation Build Options

This project provides two different approaches for building and hosting documentation, each serving different purposes and use cases.

Jekyll (docs/_config.yml)

What it does: GitHub Pages integration for live documentation website

  • Purpose: Renders your existing Markdown files in the docs/ directory as a live website
  • Technology: Jekyll static site generator (Ruby-based)
  • Hosting: GitHub Pages at https://kolchfa-aws.github.io/rest-demo
  • Content: Your existing documentation (TECH_WRITER_GUIDE.md, etc.)
  • Theme: Minima theme with professional styling
  • Automatic: Updates when you push to GitHub

generate-docs.sh Script

What it does: Creates a standalone, self-contained documentation package

  • Purpose: Generates a complete offline/portable documentation site
  • Technology: Downloads Swagger UI + converts Markdown to HTML using Pandoc
  • Hosting: Can be deployed anywhere (not tied to GitHub)
  • Content: Swagger UI + converted HTML versions of your docs + custom landing page
  • Theme: Custom CSS styling (defined in the script)
  • Manual: Run the script when you want to generate a package

📖 Detailed Guide: For comprehensive instructions on using generate-docs.sh, including troubleshooting, deployment options, and advanced usage, see Documentation Generation Guide.

Quick Start with generate-docs.sh

# Make script executable
chmod +x generate-docs.sh

# Generate documentation
./generate-docs.sh

# Serve locally (required for Swagger UI)
cd docs-site
python3 -m http.server 8081

# View at: http://localhost:8081/landing.html

Key Differences in Output

Feature Jekyll generate-docs.sh
Live API Testing No Yes (Swagger UI)
GitHub Integration Automatic Manual
Offline Use Requires GitHub Self-contained
Styling Professional theme Custom CSS
Maintenance Auto-updates Manual regeneration

What Each Creates

Jekyll creates:

https://kolchfa-aws.github.io/rest-demo/
├── tech-writer-reference/TECH_WRITER_GUIDE.html
├── tech-writer-reference/01-generated-documentation-guide.html
└── [All your markdown files as styled web pages]

generate-docs.sh creates:

docs-site/
├── index.html                    # Swagger UI for API testing
├── landing.html                  # Custom homepage
├── customer-api.yaml             # OpenAPI spec
├── tech-writer-reference/        # HTML versions of guides
└── api-assets/                   # Postman collections, etc.

Which Should You Use?

Use Jekyll for:

  • Professional documentation website
  • Easy GitHub Pages hosting
  • Automatic updates when you commit
  • Documentation-focused site

Use generate-docs.sh for:

  • Interactive API documentation with testing capability
  • Offline documentation packages
  • Self-contained deliverables for clients
  • When you need Swagger UI functionality

Recommendation

You can use both approaches depending on your needs:

  1. Jekyll for your main documentation site (live at GitHub Pages)
  2. generate-docs.sh when you need to create packages with interactive API testing

The Jekyll setup is perfect for your current documentation structure, while generate-docs.sh adds the interactive Swagger UI capability that Jekyll doesn't provide.
⚡