🎨 Fit and Finish

Author: benfalk

.github/workflows/documentation.yml

@@ -0,0 +1,31 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: benfalk/mdbook-gh-pages@main
+      - name: Build Book
+        run: |
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: 'book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CHANGELOG.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable-file MD024 -->
 # Changelog
 
 All notable changes to this project will be documented in this file. The format
@@ -8,6 +9,19 @@ is based on [Keep a Changelog], and this project adheres to [Semantic Versioning
 
 ## [Unreleased]
 
+🎨 Fit and finish for initial release with updated documentation.
+
+### Added
+
+- CI documentation job from master branch for GitHub Pages
+- `dev-book` recipe to build and serve documentation locally
+- `dev-setup` recipe and bootstrap script for local setup
+- `reqmd` CLI documentation with examples and usage instructions
+
+### Changed
+
+- Updated README with link to the online documentation
+
 ## [0.1.1] 2026-02-21
 
 🚀 Initial release of ReqMD, a tool for parsing markdown files looking for code

Justfile

@@ -16,6 +16,17 @@ dev-cli COMMAND *ARGS:
 dev-tui *ARGS:
   @cargo run -q --package reqmd_tui -- {{ARGS}}
 
+# mdbook documentation with hot reloading
+[group('dev')]
+dev-book:
+  mdbook serve -p 9033 --open
+
+# Setup environment for development
+[group('dev')]
+[no-cd]
+dev-setup:
+  @./scripts/setup-dev-environment.sh
+
 # Builds all crates in the workspace
 [group('build')]
 build:
@@ -26,17 +37,17 @@ build:
 build-rust-docs:
   cargo doc --workspace --no-deps --open
 
-# Builds and installs the CLI crate
+# Installs the CLI reqmd
 [group('build')]
 build-install-cli:
   @just _crate_install reqmd_cli
 
-# Builds and installs experimental TUI crate
+# Installs experimental TUI reqmd_tui
 [group('build')]
 build-install-tui:
   @just _crate_install reqmd_tui
 
-# runs all quick tests or specific functions
+# runs quick tests or specific functions
 [group('test')]
 test *TEST_CASES:
   @{{if TEST_CASES != "" { "just _run test-funcs " + TEST_CASES } \
@@ -48,7 +59,7 @@ test *TEST_CASES:
 test-docs:
   cargo test --doc
 
-# test code comments generate documentation
+# souce comments documentation
 [group('test')]
 test-doc-gen:
   RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

README.md

@@ -1,6 +1,60 @@
 # ReqMD: HTTP Requests in Markdown
 
+![Readable. Executable. Simple.](./docs/assets/mast-head.svg)
+
 This is a project focused on representing a human readable markdown
 format which describes HTTP requests. The goal is to be able to create
-markdown documents using this specification and leverage this tooling
+markdown documents using that specification and leverage this tooling
 to identify and send them as valid HTTP requests.
+
+To get started [read the friendly manual].
+
+[read the friendly manual]: https://benfalk.github.io/req_md/
+
+---
+
+**The tl;dr is to be able to take a document like this:**
+
+> Sample document:
+> ![Sample Document](./docs/assets/sample-doc.png)
+
+**And run commands like this:**
+
+---
+
+> List requests found in the document:
+> ![List Requests](./docs/assets/list-sample.png)
+
+---
+
+> [!Note]
+>
+> The server in the example is an echo server that replies with
+> the information it was sent.  What you are seeing returned
+> is the response of that echo server.  This helps demonstrate
+> what the details were in the requests this tool sent.
+
+---
+
+> Send first request in the document:
+> ![Send First Request](./docs/assets/send-first-request.png)
+
+---
+
+> Adds header to request with environment variable:
+> ![Environment Headers](./docs/assets/env-header-example.png)
+
+---
+
+> Can set timeouts _( Examples: 50ms, 2sec, 5min )_
+> ![Error Timeout](./docs/assets/error-timeout.png)
+
+---
+
+> Run by request found at a line number:
+> ![Run Line 18](./docs/assets/run-line-18.png)
+
+---
+
+> Dump requests to JSON:
+> ![Dump to JSON](./docs/assets/dump-to-json.png)

book.toml

@@ -2,3 +2,11 @@
 title = "ReqMD"
 authors = ["Ben Falk"]
 src = "docs"
+
+[output.html]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/benfalk/req_md"
+no-section-label = true
+
+[preprocessor.anchors-aweigh]

docs/README.md

@@ -1,4 +1,6 @@
-# Index
+# 📒 ReqMd
+
+![Readable. Executable. Simple.](./assets/mast-head.svg)
 
 Welcome to the `ReqMd` documentation! These docs are aimed at explaining the
 format specification, tools available, and structure of the codebase. The menu
@@ -8,7 +10,7 @@ the discussions] on Github with your question.
 
 [post in the discussions]: https://github.com/benfalk/req_md/discussions/categories/q-a
 
-## Inspiration
+## 🎇 Inspiration
 
 While pair-programming in 2019 a colleague demonstrated [this fantastic VS Code
 plugin] which parsed HTTP requests in a special file format. These requests could

docs/SUMMARY.md

@@ -1,7 +1,14 @@
 # Summary
 
-[Index](./README.md)
+[📒 ReqMd](./README.md)
 
 ---
 
-- [ReqMd Markdown Format](./reqmd-format.md)
+- [📐 Markdown Format](./reqmd-format.md)
+  - [🔎 Front Matter](./reqmd-format-front-matter.md)
+  - [🌐 HTTP Requests](./reqmd-format-http-requests.md)
+- [🖥️ `reqmd` CLI](./reqmd-terminal-app.md)
+  - [🕹️ Commands](./reqmd-terminal-app-commands.md)
+  - [🔌 Builtin Plugins](./reqmd-terminal-app-plugins.md)
+  - [📥 Install `reqmd`](./cli-installation-methods.md)
+- [🛠️ Development Setup](./development-setup.md)