eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions

Move zk cards to docs/zk/ for documentation restructuring #84

Merged
eblume merged 12 commits from feature/docs-restructure-phase1 into main 2026-02-03 09:13:51 -08:00
Conversation 0 Commits 12 Files changed 30 +529 -3
eblume commented 2026-02-03 07:58:08 -08:00
Owner
Copy link

Summary

  • Move all existing zettelkasten cards from docs/ to docs/zk/ as a temporary holding area
  • Update zk-docs mise task to look in the new location
  • Add docs/README.md explaining the Diataxis-based restructuring plan and target audiences

Context

This is phase 1 of a multi-phase documentation restructuring effort. The goal is to reorganize docs to follow the Diataxis framework while serving multiple audiences:

  1. Erich (owner) - knowledge graph/zk
  2. Claude/AI agents - memory and context enrichment
  3. New external readers - high-level overview
  4. Potential operators/contributors - onboarding
  5. Replicators - people wanting to duplicate the approach

Testing

  • Verified mise run zk-docs still works with the new path
  • Updated obsidian.nvim config (in ~/.config/nvim) to point to new path

Note

The obsidian.nvim config change is outside this repo but was made as part of this work.

🤖 Generated with Claude Code

## Summary - Move all existing zettelkasten cards from `docs/` to `docs/zk/` as a temporary holding area - Update `zk-docs` mise task to look in the new location - Add `docs/README.md` explaining the Diataxis-based restructuring plan and target audiences ## Context This is phase 1 of a multi-phase documentation restructuring effort. The goal is to reorganize docs to follow the Diataxis framework while serving multiple audiences: 1. Erich (owner) - knowledge graph/zk 2. Claude/AI agents - memory and context enrichment 3. New external readers - high-level overview 4. Potential operators/contributors - onboarding 5. Replicators - people wanting to duplicate the approach ## Testing - [x] Verified `mise run zk-docs` still works with the new path - [x] Updated obsidian.nvim config (in ~/.config/nvim) to point to new path ## Note The obsidian.nvim config change is outside this repo but was made as part of this work. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Phase 1 of docs restructuring: move all zettelkasten cards to a
temporary docs/zk/ subdirectory while preparing to build a new
Diataxis-based documentation structure.

- Move all existing markdown files from docs/ to docs/zk/
- Update zk-docs mise task to look in the new location
- Add docs/README.md explaining the restructuring plan

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Point to docs/README.md for the restructuring plan and clarify that
zk cards now live in docs/zk/.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add comprehensive phased plan for documentation restructuring:
- Phase 1: Foundation (current) - zk migration, tooling selection
- Phase 2: Tutorials - learning-oriented content
- Phase 3: How-to Guides - task-oriented instructions
- Phase 4: Reference - technical descriptions
- Phase 5: Explanation - concepts and decisions
- Phase 6: Integration & Cleanup

Also includes:
- Tooling evaluation table (Quartz, MkDocs, mdBook, Hugo, Docusaurus)
- Requirements (Obsidian compatibility, wiki-links, HTML/PDF output)
- Note on project naming (BlumeOps / blumeops / Blue Mops)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 1a infrastructure for building and hosting BlumeOps docs:

- Add quartz.config.ts and quartz.layout.ts for Quartz configuration
- Add containers/quartz/ with nginx-based static site server that
  downloads release bundles on startup via DOCS_RELEASE_URL env var
- Add .forgejo/workflows/build-blumeops.yaml workflow (manual trigger)
  that builds Quartz site and creates Forgejo release with tarball
- Update docs/README.md with finalized tooling choice and split
  Phase 1 into 1a (CI) and 1b (CD/hosting)

The architecture separates content versioning from infrastructure:
- Releases are versioned BlumeOps releases (v1.0.0, etc.)
- Doc tarballs are attached as release assets
- The quartz container is a generic static site server

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Keep repo root cleaner by storing quartz.config.ts and quartz.layout.ts
in docs/ alongside the content they configure. Updated workflow to copy
from the new location.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Keep the index page as a normal doc file that can be edited,
rather than generating it during the build workflow.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Clone from forge.ops.eblu.me to avoid external dependencies during builds.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Cache the Quartz clone and node_modules to speed up subsequent builds.
Only the content copy and build steps run on cache hit.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Use quartz-1, quartz-2, etc. for cache invalidation. The actual Quartz
version is determined by the mirror repo, not this key.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Simpler is better - just clone and npm ci on each build.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Leave version input empty to auto-increment patch (v_._.+1) from the
latest release. First release starts at v1.0.0.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fail early with clear error if the specified version already exists.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
eblume merged commit b8104d75ad into main 2026-02-03 09:13:51 -08:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
eblume/blumeops!84
No description provided.