mirror of
https://github.com/PR0M3TH3AN/Archivox.git
synced 2025-09-07 14:48:40 +00:00
Merge branch 'main' of https://github.com/PR0M3TH3AN/DocForge
This commit is contained in:
thePR0M3TH3AN
304
README.md
304
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.
|
||||||
|
|
||||||
[](https://github.com/yourusername/Archivox/actions/workflows/ci.yml)
|
[](https://github.com/yourusername/Archivox/actions/workflows/ci.yml)
|
||||||
|
|
||||||
**Version:** 1.0
|
## Features
|
||||||
**Date:** July 10, 2025
|
- Markdown based pages with automatic navigation
|
||||||
**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.
|
- 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.
|
## Getting Started
|
||||||
|
Install the dependencies and start the development server:
|
||||||
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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# install dependencies and start the dev server
|
|
||||||
npm install
|
npm install
|
||||||
npm run dev
|
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
|
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**:
|
## Hosting
|
||||||
- Pages from `.md` files; folder structure builds the sidebar tree automatically.
|
Upload the contents of `_site/` to any static host. For Netlify you can use the provided `netlify.toml`:
|
||||||
- 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**:
|
```toml
|
||||||
- Collapsible sidebar with expandable sections, breadcrumbs, and mobile hamburger menu.
|
[build]
|
||||||
- Header: Customizable logo, site title, version switcher.
|
command = "npm run build"
|
||||||
- Footer: Links, copyright, social icons.
|
publish = "_site"
|
||||||
- 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)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
- **Content Rules**:
|
## Documentation
|
||||||
- Max nesting: 4 levels.
|
See the files under the `docs/` directory for a more complete guide to Archivox features, customization and deployment options.
|
||||||
- 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)
|
Archivox is released under the MIT License.
|
||||||
|
|
||||||
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: ``.
|
|
||||||
- **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 %}`.
|
|
||||||
|
|
||||||
### 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<script>console.log('Page viewed: ${file}')</script>`;
|
|
||||||
return { html: html.replace('</body>', `${snippet}</body>`) };
|
|
||||||
}
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user