Logseq/Frontmatter
Logseq Frontmatter
- This page defines shared page-level frontmatter conventions for the knowledge garden.
- Page-level attributes are bare
key:: value lines at the top of the file, before any bullet. --- fences around them are illegal in Logseq; if they appear, unwrap them. tags::- treat Logseq/Tags with care
- Logseq tags have a special impact on the Logseq UI, but their implementation is buggy and inconsistent. In addition, the human gardener's use of
tags:: pre-dated the more mature Logseq/Entity entity system, and the human's rules for applying them are fuzzy and ill-defined. It's easier to use them incorrectly than to use them correctly. - As a result, their use is considered protected on existing pages: AI should not modify, add, or remove it unless explicit human instruction overrides the garden tagging rules.
- For new pages, add
tags:: only when the relevant page-type convention explicitly requires it or nearby pages establish the same pattern.
logseq-entity:: marks a page as an instance of a Logseq entity
alias:: for more convenient or alternate names
- In Logseq, if page
[[Super Long Name]] has frontmatter alias:: [[Shortname]], then clicking [[Shortname]] anywhere in the graph navigates to [[Super Long Name]]. - Appropriate uses: real alternate names, plural or contextual link surfaces, handles, acronyms, and other useful discovery forms.
Aliases are human-curated, not agent-generated
Be judicious — do not proliferate aliases
- Every alias added to the graph slows down auto-complete and may confuse the human operator about which form is canonical.
Use singular canonical names; alias the plural
- This garden uses singular canonical page names; plural or contextual references belong in
alias::.
Do not create redundant aliases
- Do not create an alias that only repeats parent namespace context already expressed by the page title.
Searching for aliases
- When auditing or pruning aliases, verify each with
rg '[[Candidate Name]]' pages/ journals/ to check graph usage before keeping it. For a graph-wide audit, nbb-logseq is more appropriate than ad hoc text search.
see-also:: for relevant, related, non-obvious pages not mentioned in the body
- The purpose of
see-also:: is to aid discovery of distant, directly pages in the garden with a compelling discovery case, and which does not appear in the body of the page. It should be used very sparingly and rarely, including no more than 2-3 items, and it should almost never include pages that are immediate parent, child or siblings in the namespace hierarchy. Standards
- Order links strongest-tie first.
- Only add a link if it is truly related and surprising — not merely adjacent in namespace or topic space.
- If a page has a
## Related section, it should contain only external hyperlinks. Related Logseq pages belong in see-also:: frontmatter, not in a body section.
Avoid obvious or tautological links
- Do not list parent namespace pages that only restate context already encoded in the page title.
Be parsimonious
- Bad Examples
- While creating Programming/Language/Concept/Declarative vs Imperative, an AI agent added
see-also:: [[Programming/Language/Func]], [[Programming/Language/Concept/Object-Oriented]].- Why these are bad: functional programming and OOP are lexicographically adjacent and structurally similar, but they are not actually related to the declarative-vs-imperative distinction. Proximity is not relatedness.
via:: for how the page's entity was discovered AKA Provenance
via:: records what caused the page to receive attention- what caused the page exist in the garden or be substantially revised or expanded in the garden
- Usually it is another entity. For example, while reading a particular person's dotfiles, if a new CLI is discovered and added to the garden, it should have
via:: [[Person/Cool Coder]]such as a journal day, import stub, or source page. - Do not use
via:: for general related reading; use see-also:: instead.
date-created:: - when the entity itself was created, published, founded, released
- The format of the date should match Logseq/Date.
Do not use date-created::
- for the date the page was added to the garden
- unless the date created is factually correct in a proven way
logseq-created-time-year:: - links an entity to its creation year, decade, or century
- The value is a link to the matching Logseq/Entity/Time/Year instance, at whatever precision is actually known — a specific year, or its decade or century when only that much is known.
- Distinct from
date-created::: that property holds the display-quality date value (day, month, or year, per Logseq/Date) and does not always resolve to a Logseq/Entity/Time/Year page. logseq-created-time-year:: always does, so every entity created in a given year, decade, or century collects there as a backlink regardless of the entity's own type. - Applies broadly, to any entity whose creation year is known: books, movies, podcast episodes, essays, musical compositions, works of art, and others.
- Set alongside
date-created::, not instead of it, when both are known.
github-link:: for the page's own source on GitHub
github-link:: holds the GitHub URL of this page's own source file in the garden repo, so a reader of the deployed web garden can open or edit the underlying Markdown.Standards
- Use the
https://github.com/<owner>/<repo>/blob/main/<path> form — the link that resolves on the web when the garden is deployed. See CursorAI Project Rule GitHub Link. - Point at the page's own file under
pages/ or journals/. For the external source of whatever a page documents, use source-link:: instead. - Encode spaces in the path as
%20; leave namespace triple underscores as they are.