docs

Author: MrPunyapal

md/architecture.md

@@ -1,35 +1,24 @@
 # Architecture
 
-## Current pipeline
+## Build pipeline
 
-The current implementation is intentionally small.
+1. `Docsmith` exposes the static and fluent API.
+2. `Builder` collects configuration: versions, hub entries, LLM export, theme, Open Graph, and more.
+3. `BuildConfig` validates the source and output paths.
+4. `SourceScanner` discovers Markdown files and reads frontmatter. Versioned builds scan one source directory per version.
+5. `CommonMarkRenderer` converts Markdown to HTML through League CommonMark with GitHub-flavored Markdown extensions.
+6. `SiteBuilder` renders pages with sidebar navigation, version pills, and the hub dropdown, and writes them to the output directory.
+7. `AssetPublisher` publishes CSS and JS assets and generates `search-index.json`, `sitemap.xml`, `.nojekyll`, and the LLM export files.
 
-1. `Docsmith` exposes the public API.
-2. `Builder` collects configuration (versions, llms-export, readme-index, theme, etc.).
-3. `BuildConfig` validates source and output paths.
-4. `SourceScanner` discovers Markdown files (respects per-version source directories).
-5. `CommonMarkRenderer` converts Markdown into HTML.
-6. `SiteBuilder` writes HTML pages, hub dropdown and version pills, search overlay, and publishes CSS/JS assets.
-7. `AssetPublisher` generates `search-index.json`, `sitemap.xml`, `.nojekyll`, `llms.txt`, `llms-full.txt`, and `export/docs.md`.
+Remote source syncing lives in `src/RemoteSources/` and runs before a build. It only writes local directories; the pipeline above never talks to the network.
 
-## Current source model
+## Document model
 
-Every discovered Markdown file is normalized into a `Document` object containing:
+Every discovered Markdown file becomes a `Document` object containing:
 
 - source path
 - relative path
 - output path
 - title
 - raw Markdown
 - rendered HTML
-
-## Current renderer
-
-The current renderer produces:
-
-- a sidebar navigation
-- a main content area
-- a generated landing page when needed
-- local CSS under `assets/app.css`
-
-This is the minimal implementation baseline, not the final architecture.

md/development.md

@@ -3,10 +3,10 @@
 ## Quality commands
 
 ```bash
-composer test:lint
-composer test:types
-composer test:unit
-composer test
+composer test:lint     # rector --dry-run && pint --test
+composer test:types    # phpstan
+composer test:unit     # pest --parallel
+composer test          # all of the above
 ```
 
 ## Tooling
@@ -28,7 +28,7 @@ That command uses Docsmith itself to read Markdown from `md/` and regenerate the
 
 ## CI / GitHub Actions
 
-The repository includes a workflow at `.github/workflows/docs.yml` that builds and commits `docs/` on every push that changes the source markdown or build script.
+The repository includes a workflow at `.github/workflows/docs.yml` that builds and commits `docs/` on every push that changes the source Markdown or the build script.
 
 If you enable generated Open Graph images, install Node, Playwright, and Chromium in CI as well:
 
@@ -85,4 +85,4 @@ jobs:
           fi
 ```
 
-Adjust the PHP version, source paths, and build command to match your project. Without Open Graph capture you can omit the Node/Playwright steps.
+Adjust the PHP version, source paths, and build command to match your project. Without Open Graph capture you can omit the Node and Playwright steps.

md/docs-hub.md

@@ -1,10 +1,10 @@
 # Docs Hub
 
-The docs hub builds several **independent** documentation sets into one site. A dropdown in the sidebar switches between them.
+The docs hub builds several independent documentation sets into one site. A dropdown in the sidebar switches between them.
 
 ## Setup
 
-Pass one entry per documentation set to `->hub()`:
+Pass one entry per documentation set to `hub()`:
 
 ```php
 use Docsmith\Docsmith;
@@ -21,13 +21,13 @@ Docsmith::make()
 
 ## How it works
 
-- Each entry gets one dropdown option and mounts under its slug (`/package-a/…`, `/package-b/…`).
-- Nothing is generated at the root: `/` simply forwards to the first entry.
+- Each entry gets one dropdown option and mounts under its slug (`/package-a/...`, `/package-b/...`).
+- Nothing is generated at the root. `/` forwards to the first entry.
 - Frontmatter `order:` still applies per page.
 
 ## Navigation order
 
-Set `navigation` on an entry to control its sidebar order. Entries are matched by title, sidebar label, or file path; pages not listed keep their natural order after the listed ones.
+Set `navigation` on an entry to control its sidebar order. Entries are matched by title, sidebar label, or file path. Pages not listed keep their natural order after the listed ones:
 
 ```php
 ->hub([
@@ -40,18 +40,18 @@ Set `navigation` on an entry to control its sidebar order. Entries are matched b
 ])
 ```
 
-Entries without `navigation` fall back to the global `->navigationOrder([...])`.
+Entries without `navigation` fall back to the global `navigationOrder([...])`.
 
 ## Hub entries with versions
 
-An entry can embed a `versions` list. The entry stays a **single** dropdown item, and its pages get version pill buttons:
+An entry can embed a `versions` list. The entry stays a single dropdown item, and its pages get version pill buttons:
 
 ```php
 ->hub([
     'auth-jobs' => [
         'label' => 'Auth Jobs',
         'source' => __DIR__ . '/md/auth-jobs',          // backs the default version
-        'navigation' => ['index.md', 'usage.md', ...],  // optional, per entry
+        'navigation' => ['index.md', 'usage.md'],       // optional, per entry
         'versions' => [
             ['slug' => 'v2', 'label' => 'v2', 'default' => true],
             ['slug' => 'v1', 'label' => 'v1', 'source' => __DIR__ . '/md/auth-jobs-1x'],
@@ -61,7 +61,7 @@ An entry can embed a `versions` list. The entry stays a **single** dropdown item
 ```
 
 - The `versions` list describes all versions of that entry.
-- The primary version — flagged `default`, else the first listed — mounts at the entry root (`/auth-jobs/…`); siblings nest under it (`/auth-jobs/v1/…`).
-- The entry-level `source` may stand in for the primary version's source (as above). Other versions need their own `source`, or resolve to `{source}/{entry-slug}/{version-slug}` when `->source()` is set.
+- The primary version (flagged `default`, otherwise the first listed) mounts at the entry root (`/auth-jobs/...`). Siblings nest under it (`/auth-jobs/v1/...`).
+- The entry-level `source` can stand in for the primary version's source, as above. Other versions need their own `source`, or they resolve to `{source}/{entry-slug}/{version-slug}` when `source()` is set.
 
-So in the built site the dropdown shows only "Auth Jobs" — never "Auth Jobs v1" — while Auth Jobs pages carry v1/v2 pills.
+In the built site the dropdown shows only "Auth Jobs", never "Auth Jobs v1", while Auth Jobs pages carry v1/v2 pills.

md/index.md

@@ -1,48 +1,60 @@
 # Docsmith
 
-Docsmith is a small PHP package for turning Markdown files into a static documentation site.
-
-## Current capabilities
-
-- Build a multi-page documentation site from a Markdown directory.
-- Generate one HTML page per Markdown file.
-- Publish local CSS assets into the output directory.
-- Publish local JS assets for search, theme toggle, and code-copy UX.
-- Support both a static entry point and a fluent builder API.
-- Build sites from the command line via the bundled `bin/docsmith` binary.
-- Render Markdown through League CommonMark with GitHub-flavored extensions.
-- Parse frontmatter metadata (`title`, `description`, `slug`, `order`, `sidebar_label`, `hidden`).
-- Hide pages from navigation, search, and pagination via frontmatter `hidden: true`.
-- Generate `search-index.json`, `sitemap.xml`, and `.nojekyll`.
-- Support repository/edit links and previous/next page navigation.
-- Build multiple versions of one documentation set with pill buttons on every page.
-- Assemble a docs hub of independent documentation sets with a sidebar dropdown.
-- Sync Markdown from remote Git repositories via smart HTTPS (no git binary, no clones).
-- Search overlay with `Cmd+K` / `Ctrl+K` keyboard shortcut.
-- AI-consumable export: `llms.txt`, `llms-full.txt`, `export/docs.md`.
-- Open Graph / Twitter card tags and generated social preview images.
-- Sidebar "Built with DocSmith" attribution that can be disabled per build.
-- Validate the package with Pest, PHPStan, Rector, and Pint.
-
-## Current status
-
-Docsmith is actively used to generate documentation for multiple packages and supports static-hosting workflows out of the box.
-
-Search includes both:
-
-- sidebar link filtering
-- global index search powered by generated `search-index.json`
-- overlay modal with keyboard shortcut
-
-## Documentation pages
-
-- Installation
-- Usage
-- Architecture
-- Development
-- Versioned Docs
-- Docs Hub
-- Remote Sources
-- Workflows
-- LLM Export
-- Open Graph
+Docsmith is a PHP package that turns a directory of Markdown files into a static documentation site.
+
+## Features
+
+- Builds one HTML page per Markdown file into a self-contained output directory.
+- Sidebar navigation with grouping, active page highlighting, and a filter box.
+- Global search backed by a generated `search-index.json`, plus a `Cmd+K` / `Ctrl+K` search overlay.
+- Dark mode, syntax-highlighted code blocks, and a copy button on snippets.
+- Frontmatter support for `title`, `description`, `slug`, `order`, `sidebar_label`, and `hidden`.
+- Versioned docs with pill buttons to switch versions.
+- Docs hub that combines several independent documentation sets under one sidebar dropdown.
+- Remote source syncing that pulls Markdown from any Git host over plain HTTPS, no `git` binary needed.
+- Generated `search-index.json`, `sitemap.xml`, `.nojekyll`, and favicon on every build.
+- Text exports for LLMs: `llms.txt`, `llms-full.txt`, and `export/docs.md`.
+- Open Graph and Twitter card tags with optional generated preview images.
+- Edit links, previous/next navigation, and a right sidebar table of contents.
+- Three ways to run it: a static API, a fluent builder, and a `vendor/bin/docsmith` CLI.
+
+## Requirements
+
+- PHP 8.3 or newer
+- Composer
+
+No framework is required. Docsmith has no Laravel or Illuminate dependency.
+
+## Quick start
+
+```bash
+composer require --dev mrpunyapal/docsmith
+```
+
+```php
+use Docsmith\Docsmith;
+
+Docsmith::build(
+    source: __DIR__ . '/md',
+    title: 'Project Docs',
+);
+```
+
+This reads Markdown from `md/` and writes the site to `docs/` by default, which works directly with GitHub Pages.
+
+## Documentation
+
+- [Installation](installation.md)
+- [Usage](usage.md)
+- [Versioned Docs](versioned-docs.md)
+- [Docs Hub](docs-hub.md)
+- [Remote Sources](remote-sources.md)
+- [Workflows](workflows.md)
+- [LLM Export](llm-export.md)
+- [Open Graph Images](open-graph.md)
+- [Architecture](architecture.md)
+- [Development](development.md)
+
+## License
+
+MIT. See [LICENSE](https://github.com/MrPunyapal/docsmith/blob/main/LICENSE) for details.

md/installation.md

@@ -8,12 +8,12 @@
 ## Install the package
 
 ```bash
-composer require mrpunyapal/docsmith
+composer require --dev mrpunyapal/docsmith
 ```
 
 ## Install the AI agent skill
 
-Docsmith ships an [Agent Skills](https://agentskills.io)-compatible skill (`docsmith-development`) that teaches AI agents — Claude Code, Cursor, Codex, OpenCode, and others — how to use the package correctly: build options, frontmatter keys, versioned docs, docs hubs, and remote source syncing.
+Docsmith ships an [Agent Skills](https://agentskills.io) compatible skill called `docsmith-development`. It teaches coding agents such as Claude Code, Cursor, Codex, and OpenCode how to use the package: build options, frontmatter keys, versioned docs, docs hubs, and remote source syncing.
 
 ### Via Laravel Boost
 
@@ -23,7 +23,7 @@ If your Laravel project uses [Boost](https://laravel.com/docs/boost), the skill
 php artisan boost:install
 ```
 
-You can also fetch it directly from this repository:
+You can also add it directly from this repository:
 
 ```bash
 php artisan boost:add-skill MrPunyapal/docsmith/resources/boost/skills
@@ -37,11 +37,11 @@ Any agent supported by the [skills CLI](https://skills.sh) can install it too:
 npx skills add MrPunyapal/docsmith/resources/boost/skills
 ```
 
-After installing, ask your agent to activate the `docsmith-development` skill when working on documentation builds.
+After installing, ask your agent to activate the `docsmith-development` skill when it works on documentation builds.
 
 ## Build documentation
 
-Docsmith can build a static site from any Markdown directory, either from PHP or from the command line.
+Docsmith builds a static site from any Markdown directory, either from PHP or from the command line.
 
 ### Command line
 
@@ -66,4 +66,4 @@ Docsmith::build(
 );
 ```
 
-That setup keeps the Markdown source in `md/` and writes the generated site into `docs/`. The main entry page is written to `docs/index.html`.
+This setup keeps the Markdown source in `md/` and writes the generated site into `docs/`. The entry page is written to `docs/index.html`.

md/llm-export.md

@@ -1,10 +1,10 @@
 # LLM Export
 
-Docsmith can generate AI-consumable exports of your documentation for use with LLMs and AI agents.
+Docsmith can export your documentation as plain text files for use with LLMs and AI agents.
 
 ## Enabling the export
 
-Export is **enabled by default**. Disable it with:
+The export is enabled by default. To turn it off, pass `false`:
 
 ```php
 Docsmith::make()
@@ -36,7 +36,7 @@ A directory listing per the [llms.txt](https://llmstxt.org/) standard:
 
 ### `llms-full.txt`
 
-Every page rendered as plain text, concatenated:
+Every page rendered as plain text and concatenated:
 
 ```
 # Installation
@@ -52,20 +52,10 @@ Set environment variables...
 
 ### `export/docs.md`
 
-Every page's raw Markdown merged into a single file with frontmatter metadata:
-
-```
-# Installation
-
-> Install the package with composer...
-
-## Requirements
-
-...
-```
+Every page's raw Markdown merged into a single file with frontmatter metadata.
 
 ## Requirements
 
 `siteUrl` must be set for correct URL generation in `llms.txt`.
 
-If no `index.md` exists in the source directory, a generated landing page is included in the export.
+If no `index.md` exists in the source directory, the generated landing page is included in the export.