Chapter 12: tree, how the page you are reading was made

A small loop closes here. You are reading a README, rendered as a web page, served by the site whose code the README describes. This package is the part of that which does no I/O: it reads what GitHub says is at a path, and turns markdown into the HTML you are looking at.

flowchart LR
  B["You open /lmjtfy.git/packages/tree/"] --> W["browse.rs asks GitHub's API, with a read-only token"]
  W --> P["tree::parse: a folder, a file, or a submodule"]
  P --> M["tree::markdown: the README as HTML, links pointed back here"]
  M --> V["view/code.rs: the page"]

Four small jobs, each with a reason:

Parsing GitHub's answer into a folder (folders first, then files), a file (text, raw bytes, or too large), or a submodule (and the commit it is pinned at, which is how you can read jevcrates from inside lmjtfy).
Parsing the whole tree for the explorer in the sidebar: GitHub's git trees API lists every file of a commit in one answer, and a submodule in it is an entry of type commit, so jevcrates' own tree is fetched at that pin and mounted under third-party/jevcrates/.
Checking a path before anything is asked about it: a path that climbs out with .. is refused, and each part is percent-encoded for GitHub.
Rendering markdown: tables, task lists, headings with anchors for the table of contents, and ```mermaid blocks left for the page to draw. A relative link in a README ([src/](src/)) is rewritten to point at the code pages, so every link you click here stays here. Raw HTML in markdown is shown as text, never run.
Reading a source file as Docco does: each run of its comments, rendered, beside the code under it (annotate, chapter 12½).

Aside: a token that must not leak. When GitHub lists a private repository's folder, each file comes with a download_url, and that URL carries a temporary access token. So the parser reads download_url for one purpose only (a submodule has none, which is how it is told from a file) and keeps nothing of it. A test checks that nothing parsed contains it.

Try it. Click the CLAUDE.md for agents tab at the top of this page. That view is tree::agents: a CLAUDE.md's first line imports the README, and the page shows that as a link instead of a line.

For the people who maintain it

Item	What
`parse(json)`	GitHub's answer for a path: `Contents::Dir` (folders first), `Contents::File` with its text, its bytes or "too large", or `Contents::Submodule` with the commit it is pinned at.
`parse_tree(json)`	GitHub's git tree for a commit, as a `Tree`: every entry, and the submodule pins. A truncated answer is refused rather than shown in part.
`Tree::mount(at, inner)`	Another repository's tree put under a path, as a submodule is.
`Tree::children(folder)`	What the explorer shows in a folder: folders first, then files.
`segments(path)`	A path's parts, or `None` if one climbs out with `..`.
`encoded(segments)`	The parts percent-encoded, for GitHub's URL.
`parent(path)`	The folder a path is in.
`annotate::sections(text, language)`	A source file as runs of comment (markdown) and the code under each, coloured: the Docco view of a file. `annotate::language(path)` says which languages are known.
`markdown(text, dir, base)`	`Rendered`: the HTML, the headings with unique anchors, and whether it has a diagram.
`link(dest, dir, base)`	Where a relative link in a file in `dir` goes, as a code page address.
`slug(text)`	A heading's anchor.
`agents(text)`	A CLAUDE.md split into its `@README.md` import and the rest.
`media_type(path, body)`	What `?raw` serves a file as. Text is always plain text, except SVG.

apps/lmjtfy/src/browse.rs does the asking, and apps/lmjtfy/src/view/code.rs draws the pages.

In this folder

Path	What
src/	The parser and the renderer.
Cargo.toml	The crate: `base64`, `pulldown-cmark`, `serde`, `serde_json`.

← Previous: Chapter 11¾, card/examples/ · Up: packages · Next: Chapter 12½, tree/src/ →