Refactoring the shadowmaker has become a bigger headache than I had originally anticipated, but it’s for the long-term health of the system, so I’m sticking to my guns. This weekend added further drama when I finally stopped running away from frontmatter and embraced it for all my metadata. Sure, scattering #ch-command directives throughout the body of the notes was insane, but fixing it is going to mean more than just adding a few metadata fields. I may have to completely change the way I use Obsidian.
While trying to integrate the many episodes of CaveTV into the site, I realized that the ontology was getting cramped. It needs to be revised to better distinguish between internal projects, external brand identities, multiple deliverables within a brand, and distinct showrooms.
What follows is the scheme we devised for what the abstractions are, how they should be tagged in Obsidian, and how the files will be managed within Hugo.
◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇◆◇
🧱 Tag-Based Ontology for Your Hugo Site
This reference defines your system of semantically meaningful tags, used in Obsidian notes via a single Tags: line, and parsed by shadowmaker to generate appropriate Hugo files and structure.
🔧 Prefix Semantics
| Tag Prefix | Meaning |
|---|---|
#ch-proj- |
Declares a new Project |
#ch-log |
Marks a Project Log |
#ch-artifact |
Marks a Project Artifact |
#ch-deliver- |
Declares a Deliverable (public output) |
#ch-brand- |
Declares a Brand (series/franchise) |
#ch-showroom- |
Declares a Showroom (navigational category) |
#ch-show-in- |
Routes a Brand to a Showroom |
-
We will have 3 fundamental types of note: a landing page, a log entry page, and an artifact page.
-
Log entries were previously called updates, and designated by the inclusion of a #ch-post tag, but even those 2 terms were already inconsistent, so I’ve replaced them with ’log’ and ‘#ch-log’ which has the added benefit of being even shorter.
-
Similarly, articles have been renamed ‘artifacts’, which better captures the role they fill in the system.
-
-
A landing page is a Markdown file that describes an entity that might have media objects or log entries attached to them.
-
For now, landing pages are used to describe projects, brands, and showrooms. The files for all three share a common information format, but are stored in different parts of the Hugo system and are rendered with different templates, so they have a common structure, but can be adapted to their specific subject.
-
Media pages are either a Markdown document in and of themselves, or they are a Markdown description of an associated media object and include links to where that object can be accessed - either local links to files on the site, or remote links to the appropriates page on an e-retailer or other websites where the media item can be found.
-
Media pages can represent any media object for any purpose. In addition to documentation or images, this could also include project deliverables, such as videos produced, books published, etc.
-
Whether a landing page describes a project, brand, or showroom is determined by which tag is used to mark it: #ch-proj-foo, #ch-brand-foo, or #ch-showroom-foo.
-
Each landing page requires a globally unique id-tag which is used to link the media pages and log pages to it. This means, for example, that when project ogg produces puppet videos, they cannot be delivered to a brand called ogg. That’s why the brand for ogg videos is called cavetv.
-
Landing pages are stored in hugo’s content tree under content/projects, content/showrooms, and content/showrooms/showroom_name/brand_name, as appropriate. So the landing page for project frank is stored in content/projects/frank/_index.md, while the cavetv brand landing page is in content/showrooms/videos/cavetv/_index.md.
-
Log entries are stored in the logs/ folder inside the folder of the landing page to which they’ve been assigned. The filename of a log file is the timestamp at which it was created.
-
This naming convention will be retroactively applied to the Obisidian source files as well, which will allow us to eliminate the timestamps database completely.
-
It also allows the title (which will be encoded as “Title: Foo bar ba” within the file) of a log entry to be changed without breaking the historical identity chain of the entry for git.
-
-
Artifact entries are stored in the artifacts/ folder under the landing page to which they’ve been assigned. So episode 11 of the cavetv brand is described in content/showrooms/videos/cavetv/artifacts/ep-011.md.
Ontology Refactor Execution Plan
0. Create git branches
-
git checkout -b ontology2in obsidian -
again in websmith
1. Rename #ch-post to #ch-log in Obsidian content
-
Create a script to replace all instances of
#ch-postwith#ch-login the Obsidian repo. -
Run the script and verify results manually in a few representative files.
-
Commit changes in the Obsidian repo with message:
Rename #ch-post to #ch-log.
2. Update Shadowmaker to recognize #ch-log
-
Modify Shadowmaker’s tag parser to process
#ch-loginstead of#ch-post. -
Test locally by running Shadowmaker on a sample input with
#ch-log. -
Commit changes in the websmith repo with message:
Update shadowmaker to use #ch-log.
3. Update Hugo template logic (if any) that relied on old tag
-
Search Hugo layout templates for use of
#ch-postorupdates. -
Modify logic to align with
#ch-logandlogs. -
Test by rebuilding Hugo site and viewing affected log pages.
-
Commit changes in the HTML output tree repo with message:
Update layout logic to use #ch-log.
4. Rename #ch-article to #ch-artifact in Obsidian content
-
Create a script to replace all instances of
#ch-articlewith#ch-artifact. -
Run the script and verify results manually.
-
Commit changes in the Obsidian repo with message:
Rename #ch-article to #ch-artifact.
5. Update Shadowmaker to recognize #ch-artifact
-
Modify Shadowmaker’s tag parser to support
#ch-artifact. -
Ensure it places artifacts into
artifacts/folder under the related landing page. -
Test with representative example.
-
Commit changes in the websmith repo with message:
Add artifact support to shadowmaker.
6. Modify Hugo layout to reflect new artifact locations
-
Update Hugo templates to read artifacts from their new location under
artifacts/. -
Rebuild Hugo and verify artifact pages are visible and correct.
-
Commit changes in the HTML output tree repo with message:
Adapt Hugo layout to artifact folder structure.
7. Introduce #ch-proj-, #ch-brand-, #ch-showroom-* naming convention
-
Create a script to rename tags in landing pages according to new ID scheme.
-
Run and verify correctness in Obsidian.
-
Commit changes in the Obsidian repo with message:
Apply new ID tag scheme for landing pages.
8. Update Shadowmaker to associate log/artifact files based on new tag format
-
Create test log and artifact pages for a brand
-
Create test log and artifact pages for a showroom
-
Modify linking logic to match prefixes
#ch-proj-,#ch-brand-, etc. -
Ensure correct association between notes and their parents.
-
Create #ch-brand-FOO for all series and collections
-
Methilien
-
13A
-
CaveTV
-
ShinyWorlds
-
-
Update existing #ch-deliver-* tags to deliver to brand tags, not to showrooms
-
Commit changes in the websmith repo with message:
Match landing pages using new tag prefix.
9. Verify and restructure folder layout under Hugo
-
Update shadowmaker output to write:
-
Projects under
content/projects/project-name/ -
Brands under
content/showrooms/...
-
-
Confirm
logs/andartifacts/folders are inside the correct landing page folder. -
Commit changes in the websmith repo with message:
Implement folder layout restructure.
10. Update Obsidian filenames of log entries to timestamp format
-
Create a script to rename log files in Obsidian repo to use timestamp format.
-
Run and verify.
-
Commit changes in the Obsidian repo with message:
Rename log entries to timestamp format.
11. Update Shadowmaker to handle timestamp-based filenames
-
Adjust file parsing logic to extract title from
Title:line in content. -
Confirm backwards compatibility is not needed (i.e., old format is no longer supported).
-
Commit changes in the websmith repo with message:
Support timestamp-based filenames for logs.
12. Update Hugo templates for logs to use Title: field
-
Modify layout to extract and display the log title from the front matter or body.
-
Confirm titles render correctly in listings and individual views.
-
Commit changes in the HTML output tree repo with message:
Use Title field for log entry titles.
13. Create a demonstration note for each of the three note types
-
Create a sample log, artifact, and landing page in the Obsidian repo.
-
Confirm they each build correctly through Shadowmaker and render properly.
-
Commit to the Obsidian repo with message:
Add demonstration notes for new ontology.
14. Document ontology in README.md or system docs
-
Create or update markdown documentation describing the new ontology rules.
-
Include tag usage, folder layout, file naming, and linking semantics.
-
Commit to the websmith repo with message:
Document updated ontology rules.
