cyb/optica.md

Ο€ 0.01% 895 words Β· 5 min

πŸ”­ optica

knowledge graph publisher β€” transforms a directory of files into a fast, navigable static site. markdown pages with wiki-links are the primary content. all other files (source code, configs, data, binaries) become graph nodes with syntax-highlighted previews

optica serve .        # dev server with live reload
optica build .        # generate static site
optica check .        # validate links, find orphans

live example: cyber.page β€” 12K pages, 10 subgraphs, built with optica

what it does

point optica at any directory. markdown files with wiki-links become navigable pages. all other files β€” .rs, .toml, .nu, .json, images, binaries β€” become graph nodes with syntax highlighting, metadata, and backlinks. the entire repo is the knowledge graph.

your-project/
β”œβ”€β”€ root/              # pages (or any directory name)
β”‚   β”œβ”€β”€ cyber/         # namespaces = directories
β”‚   β”‚   β”œβ”€β”€ truth.md
β”‚   β”‚   └── truth/     # sub-namespaces
β”‚   β”‚       β”œβ”€β”€ serum.md
β”‚   β”‚       └── coupling.md
β”‚   β”œβ”€β”€ focus.md       # root-level pages
β”‚   └── particle.md
β”œβ”€β”€ blog/              # journal entries (optional)
β”œβ”€β”€ publish.toml       # configuration
└── build/             # output (generated)

features

  • wiki-link resolution with aliases β€” page, display text, page
  • tri-kernel ranking β€” PageRank + screened Laplacian + heat kernel compute per-page probability
  • namespace hierarchy β€” directories become navigable namespaces with breadcrumbs
  • dimensional navigation β€” pages with the same name across namespaces are shown as "dimensions"
  • sub-second live reload β€” content-only edits skip the full scan and rebuild in <10ms
  • subgraph support β€” import sibling repos as subgraphs via a TOML config (optica build --subgraphs subgraphs.toml); a subgraph declares its own children in its subgraphs.toml (see Β§ subgraphs)
  • YAML frontmatter β€” tags, aliases, icons, custom properties
  • LaTeX math β€” inline $...$ and block `

$$...$$

`

  • query expressions β€” <div class="query-results"><div class="query-results-header">Query: <code>(and (page-tags tag))</code></div><p><em>No results</em></p></div> for dynamic content
  • embed transclusion β€” `
cybics/crystal/page
- - discover all pages -
` to include other pages inline - search index β€” JSON search index for client-side full-text search - graph visualization β€” interactive force-directed minimap per page - RSS feed, sitemap, SEO metadata

subgraphs

--subgraphs <file> names the repositories to fold into the graph, one subgraphs table each: name, path (absolute), optional mount (URL prefix; default the name), visibility, exclude, menu, menu_order. A top-level public_only = true makes it a public build.

a subgraph may declare its own children in a subgraphs.toml at its root, in the census format (subgraph tables: name, optional parent, path, mount, visibility, archived, orphan, local-only, exclude, menu). the root file then names only the top of each tree, and the tree is read from the repositories themselves:

# cyberia/subgraphs.toml
subgraph
name = "cyberia-my"

subgraph
name = "midao"
visibility = "private"
rule effect
mount <parent mount>/<name> unless mount is set
checkout <parent's directory>/../<name>, the sibling layout; path overrides, relative to the parent's checkout
parent the declaring subgraph; parent = "x" hangs the entry under an already loaded x instead
privacy a private parent makes its children private; public_only drops private and local-only children
menu off unless menu = true
skipped archived, orphan, the file's own repo, a missing checkout, a name or checkout already loaded, depth beyond 8 β€” each with a line on stderr
broken file a warning, not a failed build

optica serve watches every loaded checkout and reloads the tree when any subgraphs.toml changes; a child added to a tree is ingested on the next change, and watched from the next start.

quick start

# build optica
git clone <repo-url> ~/git/optica
cd ~/git/optica
cargo build --release

# serve any markdown directory
~/git/optica/target/release/optica serve ~/git/your-project --open

the scanner looks for pages in root/ (fallback: graph/, pages/). configuration via publish.toml in the project root.

page format

---
tags: topic, subtopic
alias: alternative name, another name
icon: "πŸ”­"
---
content with wiki-links and $\LaTeX$ math

## headings become namespace children

link to other pages freely. aliases resolve automatically.

architecture

scanner β†’ parser β†’ graph builder β†’ tri-kernel β†’ renderer β†’ output
Stage What it does
scanner walks filesystem, classifies files, discovers subgraphs
parser extracts YAML frontmatter, normalizes outliner format, collects wiki-links
graph resolves links, builds alias map, computes PageRank + tri-kernel
renderer markdown β†’ HTML with template support, wiki-link resolution, math
output writes HTML, search index, graph data, sitemap, RSS

the dev server watches for changes. content-only edits (no new links, no tag changes) take the fast path: skip the scan, re-parse only the changed file, re-render only the dirty page. structural changes trigger a full incremental rebuild.

configuration

publish.toml in the project root:

[site]
title = "My Knowledge Base"
base_url = "http://localhost:8080"

[content]
public_only = false
default_public = true
exclude_patterns = [".git/*", "target/*", "build/*"]

[graph]
show_minimap = true
minimap_depth = 2

[search]
enabled = true

performance

on a 12K page graph (cyber knowledge base):

Operation Time
full build ~28s
incremental rebuild (structural) ~12s
fast path (content-only edit) <10ms
live reload latency ~110ms (100ms debounce + render)

license

cyber license: don't trust. don't fear. don't beg.