Version: 1.0
Date: July 10, 2025
Overview: DocForge is a modular, lightweight static site generator (SSG) for building "Read the Docs"-style documentation sites. It prioritizes user simplicity: content is driven entirely by Markdown files in a content folder, which automatically determines page structure, titles, and sidebar links. No manual HTML, link creation, or complex setups are needed. The site is mobile-friendly, SEO-optimized, and deployable to Netlify or similar hosts.

Built with Node.js (using libraries like Eleventy for templating, marked or remark for Markdown parsing, and Vanilla JS for client-side features), DocForge generates static HTML/CSS/JS files. It's extensible via plugins and config, but defaults to a minimal, fast workflow.

This final spec incorporates core features, enhancements for usability and performance, and explicit user instructions. It's designed to be implemented as an open-source GitHub repo with a CLI starter kit (e.g., npx create-docforge my-site).

Key Features

Markdown-Driven Content and Navigation:
- Pages from .md files; folder structure builds the sidebar tree automatically.
- Supports nested sections (YAML frontmatter for overrides like titles or order).
- Index files (e.g., index.md) as section landings; alphabetical sorting with numeric prefixes for custom order.
UI and Responsiveness:
- Collapsible sidebar with expandable sections, breadcrumbs, and mobile hamburger menu.
- Header: Customizable logo, site title, version switcher.
- Footer: Links, copyright, social icons.
- Search: Client-side fuzzy search (Lunr.js) with highlighting; optional no-results suggestions.
- Page Layout: Auto-TOC from headings, right sidebar for wide screens.
Customization:
- config.yaml for site title, logo, themes, footer, dark mode, analytics.
- Shortcodes in Markdown for embeds (e.g., images, tabs, notes).
- Themes: CSS variables; pre-built options like "minimal".
- Multi-Versioning: Folder-based (e.g., content/v1/), with UI switcher.
Performance and Accessibility:
- Minified assets, lazy images, service workers for offline.
- WCAG-compliant: ARIA labels, keyboard nav, contrast checks.
- Incremental builds for fast dev.
Extensibility:
- Plugins for analytics, comments, API docs.
- Hooks for custom processing.
- i18n support via subfolders.
Search and Analytics:
- Advanced search with stemming.
- Optional metrics (e.g., Plausible integration).

Architecture

Generator Flow:
- Scan content/ recursively.
- Parse Markdown with frontmatter (gray-matter).
- Build nav JSON tree.
- Render pages with templates (Nunjucks).
- Optimize/copy assets.
- Output to _site/.
Tech Stack:
- Node.js 18+.
- Dependencies: Eleventy (core), marked/remark, Lunr.js, gray-matter.
- Dev: Live reload with Vite or Eleventy server.
- No runtime deps; pure static output.
Modularity:
- Core: Content parsing/nav generation.
- Plugins: Load from plugins/ (e.g., JS modules with hooks like onParseMarkdown).

Folder Structure

my-docforge-site/
├── content/                  # Markdown-driven content
│   ├── introduction.md       # Top-level: "Introduction"
│   ├── getting-started/      # Section: "Getting Started"
│   │   ├── index.md          # Section overview
│   │   ├── 01-install.md     # Sub-page: "Install" (numeric order)
│   │   └── image.png         # Asset (referenced in MD)
│   └── advanced/             # Section: "Advanced"
│       └── api/              # Nested: "API"
│           └── endpoints.md  # Sub-page: "Endpoints"
├── config.yaml               # Site settings
├── assets/                   # Custom static files
│   └── logo.svg              # Logo
├── plugins/                  # Optional extensions
│   └── analytics.js          # Example plugin
├── netlify.toml              # Deployment config
└── _site/                    # Built output (git-ignored)

Content Rules:
- Max nesting: 4 levels.
- File names: Hyphens/underscores to spaces for titles (e.g., quick-start.md -> "Quick Start").
- Assets: Place in content subfolders; reference relatively in MD.

Configuration File (config.yaml)

Example:

site:
  title: "DocForge Docs"
  description: "Simple static docs."
  logo: "/assets/logo.svg"
  favicon: "/assets/favicon.ico"

navigation:
  search: true
  versions:                     # Optional
    - label: "v1.0"
      path: "/v1"

footer:
  links:
    - text: "GitHub"
      url: "https://github.com"
  social:
    - icon: "twitter"
      url: "https://x.com"
  copyright: "© 2025 DocForge"

theme:
  name: "minimal"
  primaryColor: "#007bff"
  darkMode: true                # Auto/system toggle

features:
  i18n: false                   # Enable for multi-lang
  analytics:
    provider: "plausible"
    id: "my-site.io"

plugins:
  - "analytics"                 # Load from plugins/

Defaults: Sensible fallbacks if absent.
Validation: Build-time checks.

Sidebar: Tree view, highlight active, filterable on search.
Header: Logo + Title + Search + Version Switcher + Dark Toggle.
Page: Markdown-rendered body + Auto-TOC + Edit Link (GitHub).
Markdown Extensions: GFM + Shortcodes (e.g., {% image src="image.png" %}, {% note "Title" %}Content{% endnote %} for admonitions, {% tabs %}...{% endtabs %}).
Accessibility: Alt text prompts, print styles.

User Instructions: Formatting and Placing Markdown

To make DocForge truly user-friendly, include these instructions in the starter repo's README.md (which can render as a self-hosted "Getting Started" page). Emphasize simplicity: "Just write Markdown—no code required."

Placing Files and Folders

Create Sections: Use folders for top-level sections (e.g., content/guides/). Subfolders nest subsections (e.g., content/guides/basics/).
Add Pages: Place .md files inside folders. File name becomes the page title (e.g., setup.md -> "Setup"). Avoid special chars; use hyphens for spaces.
Section Overviews: Add index.md in a folder for its landing page (e.g., content/guides/index.md as "Guides" intro).
Custom Ordering: Prefix files/folders with numbers (e.g., 01-intro.md, 02-setup.md) for sorting; alphabetical otherwise.
Assets: Put images/PDFs in the same folder as the referencing MD file. Reference relatively: ![Alt text](my-image.jpg).
Nesting Limits: Keep to 3-4 levels max for usability; deeper may collapse in UI.
Multi-Version: Prefix folders like content/v1/, content/v2/; config enables switcher.
Multi-Language (Optional): Use content/en/, content/fr/ if features.i18n: true; add lang switcher.

Formatting Markdown Content

Basics: Use standard Markdown:
- # Heading 1 for main titles (auto-generates page TOC).
- ## Subheading for sections.
- - Bullet lists or 1. Numbered.
- **Bold**, _italic_, ~~strikethrough~~.
- Code: Inline `code` or blocks:
```
```python
  print("Hello")
```
- Links: [Text](url) (internal: [Link](/path), auto-resolved).
- Tables:
  
  Col1 Col2
  
  Val Val
Enhancements:
- Frontmatter: Optional YAML at top for overrides:
```
---
title: Custom Title
order: 3              # Override sorting
description: SEO meta
---
# Your content...
```
- Shortcodes: For richer elements (no extra setup needed):
  - Images: {% image src="path.jpg" alt="Desc" caption="Fig 1" %} (auto-optimizes).
  - Notes/Warnings: {% note "Info" %}Text{% endnote %}, {% warning %}Caution{% endwarning %}.
  - Tabs: {% tabs %}<br>{% tab "Tab1" %}Content1{% endtab %}<br>{% tab "Tab2" %}Content2{% endtab %}<br>{% endtabs %}.
  - Accordions: {% accordion "Section" %}Hidden content{% endaccordion %}.
- Embeds: YouTube: [Video](https://youtube.com/watch?v=ID) (renders iframe).
- Best Practices:
  - Use H1 (#) once per page for main title.
  - Add alt text to images for accessibility.
  - Keep paragraphs short for mobile readability.
  - Test embeds/assets locally.
  - For code snippets, add copy buttons via shortcode: {% code lang="js" %}code{% endcode %}.

Col1	Col2
Val	Val

Tips for Success

Preview Changes: Run npm run dev for live site at localhost:8080.
Common Issues: If a page doesn't show, check file extension (.md) and no duplicate names.
Advanced: For custom shortcodes, add plugins; else, stick to basics.

Build and Deployment

Commands (via package.json):
- npm install: Setup.
- npm run dev: Local server.
- npm run build: Generate _site/.

Netlify:

netlify.toml:

[build]
  command = "npm run build"
  publish = "_site"

Git push triggers deploys; previews for PRs.

Other Hosts: Upload _site/ to GitHub Pages, Vercel, etc.

Extensibility Roadmap

Plugins: JS files in plugins/ with hooks (e.g., add shortcodes, post-build tasks).
Themes: Override CSS in assets/custom.css.
Future: PDF export plugin, AI-assisted search suggestions.
Community: MIT license; GitHub for issues.

This spec is complete and ready for implementation. Prototype core parsing first, then add features iteratively. Total est. dev time: 2-4 weeks for MVP.

README.md

DocForge: Final Specification