From 78dae367a5b6472e3695e837994578856ac14dae Mon Sep 17 00:00:00 2001 From: davidstula Date: Fri, 18 Sep 2026 10:29:40 +0200 Subject: [PATCH 1/4] Added linter and AI review to stack docs with intentional mistakes --- docs/stack.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/stack.md b/docs/stack.md index ffc30e0..fb50ca7 100644 --- a/docs/stack.md +++ b/docs/stack.md @@ -18,16 +18,24 @@ I use Git on Windows locally. I host the repository on GitHub. To operate GitHub I use GitHub CLI in a PowerShell terminal. I'm authenticated via a Github token (the classic type) and communicating through HTTPS. +## Linter + +Markdownlint checks the the markdown files for common formatting errors. + +## AI review + +OpenAI GPT 5.6 Luna checks new and updated documentation for clarity and documentation drift. + +The AI review functionality is wrapped in a node.js script which uses the OpenAI Node.js SDK. + ## Static site generator I use [mkDocs](https://www.mkdocs.org/) to generate and serve a local version of the docs site. ## Automation -A GitHub Action workflow executes on a pull request to the "master" branch. The workflow runs on an Ubuntu runner with Python and does the following: +A GitHub Action workflow executes on a pull request to the "master" branch. The workflow runs on an Ubuntu runner and does the following: -1. Install mkDocs. -1. Check out the master branch. -1. Run ```mkdocs build```. -1. Upload the resulting ```site``` folder to Github Pages as an artifact. -1. Deploy the pages. +1. Run the linter to check markdown formatting. +1. Build the static website with the ```--strict``` argument to check for build errors. +1. Run the AI review. \ No newline at end of file From e15fe5376b1fd83702ef71a45f0c3052e14d8bb1 Mon Sep 17 00:00:00 2001 From: davidstula Date: Fri, 18 Sep 2026 11:13:53 +0200 Subject: [PATCH 2/4] Trigger PR checks against updated master From 24e33f840227aa3356d2aaacb1e4cf3bb4188d7a Mon Sep 17 00:00:00 2001 From: davidstula Date: Fri, 18 Sep 2026 12:11:55 +0200 Subject: [PATCH 3/4] Added new line at the end of stack.md --- docs/stack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/stack.md b/docs/stack.md index fb50ca7..8d58e8c 100644 --- a/docs/stack.md +++ b/docs/stack.md @@ -38,4 +38,4 @@ A GitHub Action workflow executes on a pull request to the "master" branch. The 1. Run the linter to check markdown formatting. 1. Build the static website with the ```--strict``` argument to check for build errors. -1. Run the AI review. \ No newline at end of file +1. Run the AI review. From b0aa31f3c1778778078f5b0937771a2d81ec052d Mon Sep 17 00:00:00 2001 From: davidstula Date: Sat, 19 Sep 2026 16:34:22 +0200 Subject: [PATCH 4/4] Docs: explained how to operate the pipeline, added detailed stack info. --- docs/index.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++--- docs/stack.md | 60 +++++++++++++++++++++++++++++--------------- 2 files changed, 106 insertions(+), 23 deletions(-) diff --git a/docs/index.md b/docs/index.md index 865769c..ba3f894 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,68 @@ -# Hello, world! +# Dave's Documentation Publishing Machine -This is an index file for my docs as code thing. +This project allows me to learn continuous integration and continuous deployment practices for documentation. -I **love** docs as code! +I **love** docs as code! I'm really enjoying the multidisciplinary nature of setting up and operating the pipeline: + +* writing markdown +* operating stuff from the terminal +* working with git +* setting up stuff in GitHub +* writing workflows in YAML +* vibe coding node modules +* developing AI prompts +* operating APIs + +I feel like a real hacker! :) + +## The Pipeline + +Here's how the whole thing works. + +### First-time setup + +Prerequisites: a local clone of the repository, Git, Python with pip, and Node.js 22 or newer. + +Run all commands from the repository root. The commands below use PowerShell. + +1. Install mkDocs: ```pip install mkdocs``` +1. Install the AI review dependency: ```npm ci --prefix .github/ai-review``` +1. Create an _.env_ file in the repository root with your own API key and model: + + ```dotenv + OPENAI_API_KEY=your-api-key + OPENAI_MODEL=your-model-id + ``` + +### Contributing + +Follow these steps when you want to contribute to the docs. + +1. Pull _master_. +1. Create a new local branch. +1. Write. +1. Stage the changes (don't commit). +1. Run the AI preview: ```node --env-file=.env .\.github\ai-review\review.mjs --preview``` +1. Run ```mkdocs serve``` to check how your work looks on the generated site. Open in your browser. +1. Commit. +1. Create a PR for merging your branch to _master_. + +### Automatic PR checks + +A GitHub Actions workflow runs when a PR is created or when you push the PR branch. The workflow is defined in _.github\workflows\pr-checks.yml_. + +The AI review is skipped for PRs from forks. + +This happens automatically: + +1. Run MarkdownLint to validate the markdown. Only the _docs_ folder is validated. The workflow stops if it finds errors. +1. Run ```mkdocs build --strict``` to check that the site builds. If the build fails, the workflow stops. +1. Generate a diff of your changes against master. +1. Run the AI review (_.github\ai-review\review.mjs_) on the diff. +1. Post the AI review as a PR comment. Token consumption information appears in the GitHub Actions job summary. The AI review is advisory, findings do not block merging the PR. + +After I review the PR, I merge it manually. + +### Publishing + +A GitHub Actions workflow builds and publishes the site in GitHub Pages when changes to _docs/_ or _mkdocs.yml_ are pushed to _master_, including when a PR is merged. You can also run it manually from the Actions tab. The workflow is defined in _.github\workflows\builddocs.yml_. diff --git a/docs/stack.md b/docs/stack.md index 8d58e8c..2710da0 100644 --- a/docs/stack.md +++ b/docs/stack.md @@ -1,41 +1,61 @@ # My Docs as Code stack -I'm using these tools in the pipeline. +This page details the tools used in the pipeline and my reasoning for choosing those tools. For details about the pipeline itself, see [the home page](index.md). ## Authoring -I write markdown files with **Notepad++**. +I write markdown and the associated infrastructure code with **Notepad++**. It's the simplest tool that I already had on my computer. It is sufficient for this small prototype. -I use the following plugins: +I use [AnotherMarkdown](https://github.com/ezyuzin/NppAnotherMarkdown) to preview the rendered markdown. -- [AnotherMarkdown](https://github.com/ezyuzin/NppAnotherMarkdown) +Future consideration: I will switch to VS Code for production projects as it provides a more integrated coding experience. -## Versioning +## Source control -I use Git on Windows locally. I host the repository on GitHub. +Locally, I use **Git for Windows**. The [remote repository](https://github.com/davidstula/docsmachine) lives on **GitHub**. -[Open the repository](https://github.com/davidstula/docsmachine) +I use **GitHub CLI** from a **PowerShell** terminal. I'm authenticated via a GitHub token (the classic type) and communicate through HTTPS. -To operate GitHub I use GitHub CLI in a PowerShell terminal. I'm authenticated via a Github token (the classic type) and communicating through HTTPS. +GitHub is the most obvious choice for learning continuous integration practices and tools, as it's widely used and has detailed documentation. -## Linter +## Creating outputs -Markdownlint checks the the markdown files for common formatting errors. +I use **[mkDocs](https://www.mkdocs.org/)** to generate a static site. -## AI review +Locally, I use the mkDocs _serve_ function to preview the end result. On GitHub, I use mkDocs to generate the site in a GitHub Actions workflow. -OpenAI GPT 5.6 Luna checks new and updated documentation for clarity and documentation drift. +mkDocs uses its default settings. -The AI review functionality is wrapped in a node.js script which uses the OpenAI Node.js SDK. +I chose mkDocs randomly. I didn't want to spend time evaluating static side generators so I just picked the first one I found. -## Static site generator +Future consideration: For simple pipelines such as this, I would use Jekyll, which is already integrated in GitHub. -I use [mkDocs](https://www.mkdocs.org/) to generate and serve a local version of the docs site. +## Publishing -## Automation +I use **GitHub Pages** to publish the generated site. -A GitHub Action workflow executes on a pull request to the "master" branch. The workflow runs on an Ubuntu runner and does the following: +A **GitHub Actions** workflow uses mkDocs to generate the output and publish it when changes to _docs/_ or _mkdocs.yml_ are pushed to _master_, including when a PR is merged. The workflow can also be run manually from the Actions tab. -1. Run the linter to check markdown formatting. -1. Build the static website with the ```--strict``` argument to check for build errors. -1. Run the AI review. +## Content review + +The documentation content goes through automated review. The following happens when a new pull request is created: + +1. **MarkdownLint** validates the markdown code. +1. **mkDocs** checks that the site builds with the _--strict_ option. +1. OpenAI's **GPT-5.6 Luna** LLM reviews the content for clarity. + +The AI review runs only if the markdown validation and build pass. It is skipped for PRs from forks. + +I chose MarkdownLint as it's available as a published GitHub action, is widely used, and has high ratings. + +I chose GPT-5.6 Luna as the model that does the review because it's cheap and provides decent quality of responses. + +### Local AI review + +The same Node.js module can be used locally with the ```--preview``` argument to generate an AI review of staged changes without having to commit the changes. + +### AI review stack + +A **Node.js** module orchestrates the AI review. It calls **OpenAI's JavaScript SDK** and uses GitHub CLI to post the review as a comment to the pull request. + +These are tools I was somewhat familiar with so they represent the obvious choice for learning.