Recipes
Setups for common workflows, ready to copy.
#Check the tree in CI
Fail the build when someone forgot to update the README. uvx runs fsg without installing it:
.github/workflows/ci.yml
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
- run: uvx fsg --check README.md Pin fsgUse
uvx fsg@0.4.0 so a new release cannot change the tree in your build.#Update with pre-commit
fsg --setup-hook README.md writes this for you. To add it by hand:
.pre-commit-config.yaml
repos:
- repo: https://github.com/KarnesTH/fsg
rev: v0.4.0
hooks:
- id: fsg # updates README.md
# - id: fsg-check # only checks, e.g. in CI For another file, override the arguments: args: [--update, docs/structure.md].
#Monorepo with several trees
One marker pair per package, each with its own path and options. A single fsg --update README.md updates all of them.
README.md
### API
<!-- fsg:start path=packages/api depth=2 -->
<!-- fsg:end -->
### Web
<!-- fsg:start path=packages/web/src dirs-only summary -->
<!-- fsg:end --> #Only source files
Show the Python files and leave the tests out:
$ fsg -i "*.py" -e tests --summary #Share a tree in an issue
Copy the first two levels and paste them into a GitHub issue or a chat. The code fence is included, so it renders right away.
$ fsg -d 2 --copy
✔ tree copied to clipboard #Tree in another file
Keep the README short and put the structure into your docs. path in the marker is relative to that file:
docs/architecture.md
<!-- fsg:start path=../src depth=3 -->
<!-- fsg:end --> $ fsg --setup-hook docs/architecture.md