1# Chapter 12: tree, how the page you are reading was made
2
3A small loop closes here. You are reading a README, rendered as a web page,
4served by the site whose code the README describes. This package is the
5part of that which does no I/O: it reads what GitHub says is at a path, and
6turns markdown into the HTML you are looking at.
7
8```mermaid
9flowchart LR
10  B["You open /lmjtfy.git/packages/tree/"] --> W["browse.rs asks GitHub's API, with a read-only token"]
11  W --> P["tree::parse: a folder, a file, or a submodule"]
12  P --> M["tree::markdown: the README as HTML, links pointed back here"]
13  M --> V["view/code.rs: the page"]
14```
15
16Four small jobs, each with a reason:
17
18- **Parsing GitHub's answer** into a folder (folders first, then files), a
19  file (text, raw bytes, or too large), or a submodule (and the commit it is
20  pinned at, which is how you can read jevcrates from inside lmjtfy).
21- **Parsing the whole tree** for the explorer in the sidebar: GitHub's git
22  trees API lists every file of a commit in one answer, and a submodule in it
23  is an entry of type `commit`, so jevcrates' own tree is fetched at that pin
24  and mounted under `third-party/jevcrates/`.
25- **Checking a path** before anything is asked about it: a path that climbs
26  out with `..` is refused, and each part is percent-encoded for GitHub.
27- **Rendering markdown**: tables, task lists, headings with anchors for the
28  table of contents, and ` ```mermaid ` blocks left for the page to draw.
29  A relative link in a README (`[src/](src/)`) is rewritten to point at the
30  code pages, so every link you click here stays here. Raw HTML in markdown
31  is shown as text, never run.
32- **Reading a source file as Docco does**: each run of its comments,
33  rendered, beside the code under it (`annotate`, chapter 12½).
34
35> **Aside: a token that must not leak.** When GitHub lists a private
36> repository's folder, each file comes with a `download_url`, and that URL
37> carries a temporary access token. So the parser reads `download_url` for
38> one purpose only (a submodule has none, which is how it is told from a
39> file) and keeps nothing of it. A test checks that nothing parsed contains
40> it.
41
42> **Try it.** Click the `CLAUDE.md for agents` tab at the top of this page. That view is
43> `tree::agents`: a CLAUDE.md's first line imports the README, and the page
44> shows that as a link instead of a line.
45
46## For the people who maintain it
47
48| Item | What |
49| --- | --- |
50| `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. |
51| `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. |
52| `Tree::mount(at, inner)` | Another repository's tree put under a path, as a submodule is. |
53| `Tree::children(folder)` | What the explorer shows in a folder: folders first, then files. |
54| `segments(path)` | A path's parts, or `None` if one climbs out with `..`. |
55| `encoded(segments)` | The parts percent-encoded, for GitHub's URL. |
56| `parent(path)` | The folder a path is in. |
57| `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. |
58| `markdown(text, dir, base)` | `Rendered`: the HTML, the headings with unique anchors, and whether it has a diagram. |
59| `link(dest, dir, base)` | Where a relative link in a file in `dir` goes, as a code page address. |
60| `slug(text)` | A heading's anchor. |
61| `agents(text)` | A CLAUDE.md split into its `@README.md` import and the rest. |
62| `media_type(path, body)` | What `?raw` serves a file as. Text is always plain text, except SVG. |
63
64`apps/lmjtfy/src/browse.rs` does the asking, and
65`apps/lmjtfy/src/view/code.rs` draws the pages.
66
67## In this folder
68
69| Path | What |
70| --- | --- |
71| [src/](src/) | The parser and the renderer. |
72| [Cargo.toml](Cargo.toml) | The crate: `base64`, `pulldown-cmark`, `serde`, `serde_json`. |
73
74← Previous: [Chapter 11¾, card/examples/](../card/examples/) · Up: [packages](../) · Next: [Chapter 12½, tree/src/](src/) →