Skip to content

feat(popola,sitegen): add documentation tooling for agents and static site generator#11

Open
Xe wants to merge 31 commits intomainfrom
Xe/popola
Open

feat(popola,sitegen): add documentation tooling for agents and static site generator#11
Xe wants to merge 31 commits intomainfrom
Xe/popola

Conversation

@Xe
Copy link
Copy Markdown
Member

@Xe Xe commented Feb 4, 2026 •
edited
Loading

Summary

  • Add cmd/popola - a tool for authoring documentation for AI agents
  • Add cmd/sitegen - a static site generator for markdown documentation
  • Integrates agent skills for improved prose generation (writing style guide, stop-slop)
  • Outputs markdown with YAML front matter for static site generation
  • Generates llms.txt files for AI consumption
  • Produces styled HTML output with templ templates

Details

This PR adds two complementary tools for documentation workflows:

Popola (cmd/popola)

A documentation generation tool that:

  1. Takes structured input (title, description, tags, sources)
  2. Uses AI agent skills (Xe Iaso's writing style guide, stop-slop) to generate polished prose
  3. Outputs markdown with YAML front matter for static site generators
  4. Uses xe-style-guide skill for consistent voice and tone

Sitegen (cmd/sitegen)

A static site generator that:

  1. Scans content directories for markdown files with YAML frontmatter
  2. Parses frontmatter to extract title and description
  3. Generates llms.txt files aggregating all content metadata
  4. Produces styled HTML pages using templ templates
  5. Creates index pages showing all non-index pages
  6. Supports configurable output directories and preambles

Configuration

Both tools use YAML configuration (sitegen.yaml, testinput.json) for flexibility.

Test plan

  • Code compiles with go build ./...
  • Code formatted with npm run format
  • Tests pass with go test ./...
  • Manual testing of both tools

Future work

Planned features not yet implemented:

  • Commit generated prose to a GitHub repo
  • llms.txt per folder (currently generates one per site)
  • Slack/GitHub Actions flow for generating new posts
  • Reference other llms.txt files

Xe added 3 commits February 4, 2026 13:13
@Xe
feat: add cmd/popola for authoring documentation for agents
22c0fd4 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
chore(popola): add agent skills to make writing better
414c88f 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(popola): use Xe Iaso's writing style guide
236d9a5 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
Copy link
Copy Markdown
Member Author

Xe commented Feb 4, 2026

Closes: TIG-7492

Xe added 17 commits February 4, 2026 15:17
@Xe
feat(sitegen): add initial command structure
abb7544 
- Add main.go with CLI flag parsing
- Add config.go for YAML configuration loading
- Add stub sitegen.go for generation logic
- Add README.md with usage documentation

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): add markdown and frontmatter dependencies
22d8519 
- go.abhg.dev/goldmark/frontmatter for YAML frontmatter parsing
- github.com/yuin/goldmark for markdown to HTML conversion
- gopkg.in/yaml.v3 for YAML config parsing

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): add frontmatter parsing with tests
d7be969 
- Parse YAML frontmatter for title, description, body
- Require title and description fields
- Fail with clear error messages on missing fields
- Table-driven tests for various scenarios

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): add content directory scanning
affefb0 
- Recursively scan content_dir for .md files
- Track index.md files separately
- Build page metadata with input/output paths
- Test with nested directory structure

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): add templ templates and CSS styling
a47c54a 
- Add templ templates for HTML generation
- Embed CSS directly using go:embed
- Style based on Xess.css with Tigris-inspired colors
- Rename Page template to PageView to avoid struct name conflict

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): add HTML page generation
cba6ca7 
- Generate styled HTML from markdown with frontmatter
- Copy original .md files alongside HTML
- Preserve directory structure in output
- Test HTML output contains title and content
- Keep CSS files in main sitegen directory

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): add llms.txt generation
ddcbfbf 
- Generate llms.txt with links to all pages
- Format: [title](path): description
- Clean descriptions by removing newlines and extra spaces
- Include config preamble at top of file

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): wire up full generation pipeline
5deb783 
- Scan content directory for markdown files
- Parse frontmatter for all files
- Generate HTML pages with templates
- Copy original markdown files
- Generate llms.txt with all pages
- Add integration test for full flow

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
chore: add var/ to gitignore for sitegen output
a144844 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
docs: add sitegen to main README
0f36e7e 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
docs: expand popola description in README
9cdae9a 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): skip index.md files in llms.txt
4c6fb8f 
- Don't include index.md files in generated llms.txt
- Update tests to verify index files are excluded

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
docs: add sitegen plan
da1a9d2 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
chore: npm run format
ada6a24 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
chore(popola): cleanups
566de35 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
refactor(sitegen): simplify index page list to append to body
3656e5c 
Remove separate PageIndex template. For index.md files, just
append the child page list to the end of the body HTML.

Assisted-by: GLM 4.7 via Claude Code

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(sitegen): root index shows all non-index pages
0f6091f 
For the root index.md, show ALL non-index pages from all
directories on one page. Subdirectory indexes still only
show their local pages.

Also add index.md files for migration/ and tutorials/.

Assisted-by: GLM 4.7 via Claude Code

Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe Xe changed the title feat(popola): add documentation generation tool for agents feat(popola,sitegen): add documentation tooling for agents and static site generator Feb 4, 2026
Xe added 8 commits February 4, 2026 16:44
@Xe
docs(popola): rewrite README with clear usage instructions
4881faa 
Replace the minimal README with a complete description based on source
code analysis. Includes input format, output behavior, how it works,
flags reference, and usage example.

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(popola): add output folder flag and improve tool logging
6a4fd32 
- Add --output-folder flag (default: ./var) for generated content
- Template output folder in optimized.tmpl.txt prompt
- Add todo.go for parsing TodoWrite tool inputs from map[string]any
- Improve tool logging with nice formatting:
  - TodoWrite: logs each todo with status and content
  - mcp__web-reader__webReader: logs URL being fetched
  - Read/Write/Edit: log file path instead of full JSON
- Update testinput.json for AWS Node.js tutorial
- Update sitegen.yaml preamble for generative agents

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(popola): auto-commit generated content to git
85d0e5c 
- Add go-git dependency for git operations from Go code
- Add commitChanges function that:
  - Opens git repo in output folder
  - Finds changed files in output folder
  - Stages and commits them with "docs: <topic>" message
  - Includes Assisted-by and Signed-off-by footers
- Call commitChanges after agent succeeds
- Add npm run build script that outputs to ./var/bin
- Update AGENTS.md to document build output location

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
fix(sitegen): use MDPath for llms.txt links instead of URLPath
3fa5ad1 
- Add MDPath field to Page struct for markdown file links
- URLPath now contains HTML links (.html extension)
- MDPath contains markdown links (.md extension)
- Update llms.txt generation to use MDPath for references
- Update tests to use MDPath field

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
fix(popola): rename NoChangesToCommit to ErrNoChangesToCommit
4ab26cc 
Follow Go naming conventions for error variables (ST1012).

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
docs(popola): clean up redundant prompt rules
9d089cc 
Merge duplicate rules about not exploring the repo and using web-reader.

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
test(popola): update test topic for AWS SDK to Tigris SDK migration
014332b 
Change test input to cover switching from AWS SDK to Tigris SDK in JavaScript,
referencing the Tigris storage README and AWS SDK v3 docs.

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
refactor(popola): use output folder as working directory
3357eb7 
Set the agent's working directory to the output folder instead of the repo root,
so all generated content goes directly to the target location.

Assisted-by: GLM 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
Xe added 3 commits February 9, 2026 17:09
@Xe
feat(popola): add SEO/AEO skill
2116a34 
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
feat(popola): parse Bash tool uses and add WebFetch/model config
a60b349 
Extract command and description from Bash tool input for cleaner log
output. Also add WebFetch to allowed tools and set the model explicitly.

Assisted-by: Claude Opus 4.6 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
@Xe
refactor(popola): extract event handling and deduplicate tool logging
ae1938f 
Extract handleEvent and logToolUse helpers to flatten the deeply nested
event loop. Use the model flag instead of hardcoding it, validate the
output folder on startup, and add session context to the logger.

Assisted-by: Claude Opus 4.6 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Xe