Version: 1.0
Date: July 10, 2025
Overview: Archivox 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), Archivox 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-archivox my-site).

Quick Start

# install dependencies and start the dev server
npm install
npm run dev

# build the static site
npm run build

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-archivox-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: "Archivox 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 Archivox"

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

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

pluginsDir: "plugins"          # Folder for custom plugins
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 Archivox 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.

Configuring Versions and Languages

Add available versions under navigation.versions in config.yaml and create matching folders (e.g., content/v1/, content/v2/).
Enable multiple languages by setting features.i18n: true and using subfolders such as content/en/ or content/fr/.

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 = "CI= npm run build"  # Avoid CI treating warnings as errors
  publish = "_site"
```
- Connect the repo to Netlify by selecting New site from Git in your Netlify dashboard and picking this repository. Netlify will read netlify.toml so no extra setup is required. Once linked, pushes to main automatically build and deploy the site and pull requests get preview URLs.
- Ensure the generated _site/ folder is git-ignored (see .gitignore) so deployments always use a fresh build.
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: Customize variables in assets/theme.css or override styles in assets/custom.css. A built-in dark-mode toggle stores preference in local storage.
Future: PDF export plugin, AI-assisted search suggestions.
Community: MIT license; GitHub for issues.

Creating Custom Plugins

Plugins are plain Node.js modules placed in the folder defined by pluginsDir. Each module can export hook functions which Archivox calls during the build:

module.exports = {
  // Modify markdown before frontmatter is parsed
  async onParseMarkdown({ file, content }) {
    return { content };
  },
  // Modify the final HTML of each page
  async onPageRendered({ file, html }) {
    return { html };
  }
};

Example plugins/analytics.js:

module.exports = {
  onPageRendered: async ({ html, file }) => {
    const snippet = `\n<script>console.log('Page viewed: ${file}')</script>`;
    return { html: html.replace('</body>', `${snippet}</body>`) };
  }
};

Enable it in config.yaml:

pluginsDir: "plugins"
plugins:
  - "analytics"

Running npm run build will load the plugin and execute its hooks.

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

Archivox: Final Specification