Directory structure

docs
├── adr
│   ├── 20240416-architecture-v2.md
│   ├── 20240916-llm-choice.md
│   ├── 20240916-rag-framework-choice.md
│   ├── index.md
│   └── template.md
└── l4b-static
    └── images
        ├── favicon-16x16.png
        └── favicon-32x32.png

Makefile

Filename: Makefile

add-adr:
    docker run --rm -ti -v $$(pwd):/workdir -p 4004:4004 thomvaill/log4brains adr new $(ARGS)

preview:
    docker run --rm -ti -v $$(pwd):/workdir -p 4004:4004 thomvaill/log4brains preview $(ARGS)

build:
    docker run --rm -ti -v $$(pwd):/workdir -p 4004:4004 thomvaill/log4brains build $(ARGS)
    cp -R docs/l4b-static/* .log4brains/out/l4b-static/

# Serve the built docs on port 5002
serve:
    cd .log4brains/out && python3 -m http.server 5002

GitHub Action

Filename: .github/workflows/publish-log4brains.yml

name: Publish Log4brains
on:
  push:
    branches:
      - main
  workflow_dispatch: {}

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    if: ${{ !github.event.pull_request.draft }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - uses: pre-commit/action@v3.0.0

  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          persist-credentials: false # required by JamesIves/github-pages-deploy-action
          fetch-depth: 0 # required by Log4brains to work correctly (needs the whole Git history)
      - name: Install Node
        uses: actions/setup-node@v3
        with:
          node-version: "16"
      - name: Install and Build Log4brains
        run: |
          npm install -g log4brains
          log4brains build
          cp -R docs/l4b-static/* .log4brains/out/l4b-static/

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .log4brains/out

Usage example

Filename: docs/adr/index.md

# Architecture knowledge base

Welcome 👋 to the architecture knowledge base of Project ![Project](/l4b-static/images/favicon-16x16.png).
You will find here all the Architecture Decision Records (ADR) of the project.

Originally published as GitHub Gist #f041a013db9a730d2f2889663d1956f6

social