Merge pull request #33 from PR0M3TH3AN/codex/identify-potential-feature-additions

Improve docs and add integration tutorial

README.md

@@ -50,6 +50,6 @@ Upload the contents of `_site/` to any static host. For Netlify you can use the
 ```
 
 ## Documentation
-See the files under the `docs/` directory for a more complete guide to Archivox features, customization and deployment options.
+See the files under the `docs/` directory for a full guide to Archivox including an integration tutorial for existing projects.
 
 Archivox is released under the MIT License.

docs/content/01-getting-started/01-install.md

@@ -1,11 +1,11 @@
 # Install Archivox
 
-1. Clone or download this repository.
-2. Run `npm install` to install dependencies.
+1. Clone or download this repository, or run `npx create-archivox my-docs --install` to generate a starter project automatically.
+2. Inside the project directory run `npm install` to fetch dependencies.
 3. Start the local development server:
 
 ```bash
 npm run dev
 ```
 
-The site will be available at `http://localhost:8080`.
+Open `http://localhost:8080` to view your site as you edit files.

docs/content/01-getting-started/02-build.md

@@ -1,9 +1,9 @@
 # Build the Site
 
-When you're ready to generate the static files, run:
+Run the build script whenever you want to publish new changes:
 
 ```bash
 npm run build
 ```
 
-The output appears in the `_site/` folder.
+The compiled HTML, CSS and JavaScript are placed in the `_site/` directory ready to upload to any static host.

docs/content/01-getting-started/index.md

@@ -1,3 +1,3 @@
 # Getting Started
 
-This section walks you through installing Archivox and creating your first site.
+Archivox turns a folder of Markdown files into a searchable documentation site. Follow these pages to install the dependencies, preview your docs locally and produce the final static files.

docs/content/02-features/index.md

@@ -1,8 +1,8 @@
 # Features Overview
 
-Archivox automatically turns your Markdown files into a full documentation site with a responsive layout and search.
+Archivox automatically converts your Markdown files into a full documentation site with built-in search and a responsive layout. Key features include:
 
-* Sidebar navigation generated from folders (prefix names with numbers to control order)
-* Collapsible mobile menu and dark-mode switch
-* Client-side search powered by Lunr.js
-* Shortcodes for rich content (images, tabs, notes)
+* **Automatic navigation** – folders become sidebar sections so you can structure docs however you like.
+* **Dark mode** – a toggle is included for readers who prefer dark backgrounds.
+* **Client-side search** – Lunr.js indexes your content to allow instant search without a backend.
+* **Shortcodes for rich content** – use simple syntax for images, tabs and notes.

docs/content/03-customization/index.md

@@ -1,3 +1,3 @@
 # Customizing Your Site
 
-Site settings live in `config.yaml`. You can change the title, logo, colors, and enable features like analytics or multi-language support.
+Most options live in `config.yaml`. Update the `site` block to set your title, add a logo or tweak colors. You can also enable features such as analytics or multilingual content.

docs/content/03-customization/plugins.md

@@ -1,6 +1,6 @@
 # Writing Plugins
 
-Create JavaScript modules in the `plugins/` directory. Export hook functions such as `onParseMarkdown` or `onPageRendered` to modify the build.
+Place JavaScript files in the `plugins/` directory. Export hook functions such as `onParseMarkdown` or `onPageRendered` to modify the build process. Hooks receive data objects that you can transform before Archivox writes the final files.
 
 Example:
 

docs/content/04-deployment/index.md

@@ -1,9 +1,11 @@
 # Deployment
 
-Archivox sites output to the `_site/` folder. Host the contents on any static server. For Netlify, include a `netlify.toml` file:
+Running `npm run build` generates the `_site/` folder. Upload its contents to any static host. For Netlify, include a `netlify.toml` file:
 
 ```toml
 [build]
   command = "npm run build"
   publish = "_site"
 ```
+
+Other hosts work similarly—just make sure your CI system outputs the `_site/` directory.

docs/content/05-advanced/api/endpoints.md

@@ -1,3 +0,0 @@
-# API Endpoints
-
-If you expose APIs for your project, document them here. Archivox does not impose any format—just write Markdown.

docs/content/05-advanced/index.md

@@ -1,3 +0,0 @@
-# Advanced Topics
-
-Use this section for in-depth guides, such as API references or multi-version setups.

docs/content/05-project-integration/01-setup.md

@@ -0,0 +1,18 @@
+# 1. Download the Starter
+
+Create a `docs/` folder inside your project and fetch the Archivox starter with `wget`:
+
+```bash
+mkdir docs && cd docs
+wget -O archivox.tar.gz https://codeload.github.com/PR0M3TH3AN/Archivox/tar.gz/refs/heads/main
+# extract just the starter directory
+mkdir tmp && tar -xzf archivox.tar.gz -C tmp
+mv tmp/Archivox-main/starter/* .
+rm -rf archivox.tar.gz tmp
+```
+
+Install the dependencies locally:
+
+```bash
+npm install
+```

docs/content/05-project-integration/02-config.md

@@ -0,0 +1,13 @@
+# 2. Understand `config.yaml`
+
+The generated `config.yaml` contains basic site information. Adjust the values to match your project:
+
+```yaml
+site:
+  title: "My Project Docs"
+  description: "Documentation for the project"
+navigation:
+  search: true
+```
+
+Change the title and description to what you want displayed in the sidebar and `<head>` tags.

docs/content/05-project-integration/03-content.md

@@ -0,0 +1,13 @@
+# 3. Add Documentation Content
+
+Place Markdown files in the `content/` directory. Each folder becomes a sidebar section. Prefix names with numbers to control order:
+
+```
+content/
+  01-getting-started/
+    01-install.md
+  02-guides/
+    feature-a.md
+```
+
+The numbers are stripped from page titles but keep everything sorted.

docs/content/05-project-integration/04-build.md

@@ -0,0 +1,9 @@
+# 4. Build and Publish
+
+Use the provided `package.json` scripts to generate the site:
+
+```bash
+npm run build
+```
+
+The static files appear in the `_site/` directory. Configure your CI/CD pipeline to run this command and upload `_site/` as your documentation site.

docs/content/05-project-integration/index.md

@@ -0,0 +1,3 @@
+# Using Archivox Inside Another Project
+
+This tutorial shows how to add Archivox to an existing codebase with only a few commands. We'll download the starter files, walk through the configuration and content structure, then configure your build step so the docs publish alongside your project.

docs/content/index.md

@@ -12,4 +12,4 @@ npm run build # generate the _site/ folder
 
 Archivox converts Markdown files inside a `content/` folder into a full documentation site with search, navigation, and responsive design.
 
-Check the **Getting Started** section to learn how to install and run Archivox locally.
+Check the **Getting Started** section to learn how to run Archivox locally and the **Project Integration** guide to drop Archivox into an existing codebase.

starter/content/02-advanced/api/endpoints.md

@@ -1,3 +0,0 @@
-# API Endpoints
-
-Document your API here.