diff --git a/README.md b/README.md index 52f7453..2b6adf7 100644 --- a/README.md +++ b/README.md @@ -1,285 +1,55 @@ -# Archivox: Final Specification +# Archivox + +Archivox is a lightweight static site generator aimed at producing documentation sites similar to "Read the Docs". Write your content in Markdown, run the generator, and deploy the static files anywhere. [![Build Status](https://github.com/yourusername/Archivox/actions/workflows/ci.yml/badge.svg)](https://github.com/yourusername/Archivox/actions/workflows/ci.yml) -**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. +## Features +- Markdown based pages with automatic navigation +- Responsive layout with sidebar and search powered by Lunr.js +- Simple configuration through `config.yaml` +- Extensible via plugins and custom templates -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 +## Getting Started +Install the dependencies and start the development server: ```bash -# install dependencies and start the dev server npm install npm run dev +``` -# build the static site +The site will be available at `http://localhost:8080`. Edit files inside the `content/` directory to update pages. + +To create a new project from the starter template you can run: + +```bash +npx create-archivox my-docs --install +``` + +## Building +When you are ready to publish your documentation run: + +```bash npm run build ``` +The generated site is placed in the `_site/` folder. -## Key Features +## Customization +- **`config.yaml`** – change the site title, theme options and other settings. +- **`plugins/`** – add JavaScript files exporting hook functions such as `onPageRendered` to extend the build process. +- **`templates/`** – modify or replace the Nunjucks templates for full control over the HTML. -- **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. +## Hosting +Upload the contents of `_site/` to any static host. For Netlify you can use the provided `netlify.toml`: -- **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 - -1. **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/`. - -2. **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. - -3. **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) +```toml +[build] + command = "npm run build" + publish = "_site" ``` -- **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. +## Documentation +See the files under the `docs/` directory for a more complete guide to Archivox features, customization and deployment options. -## Configuration File (config.yaml) - -Example: - -```yaml -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. - -## Navigation and UI Details - -- **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 %}
{% tab "Tab1" %}Content1{% endtab %}
{% tab "Tab2" %}Content2{% endtab %}
{% 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 %}`. - -### 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`: - ```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: - -```js -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`: - -```js -module.exports = { - onPageRendered: async ({ html, file }) => { - const snippet = `\n`; - return { html: html.replace('', `${snippet}`) }; - } -}; -``` - -Enable it in `config.yaml`: - -```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. +Archivox is released under the MIT License.