devpage 0.2.3

Live documents from a repository: sites, docs and slides from Markdown, and UI designs drawn from code — with comments, link checking and PDF
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Writing a doc

How to write a **doc** — a design doc, a PRD, a proposal: a document read top to
bottom, like a Word file. It covers splitting a doc into chapters, the outline
that follows the reader, links between chapters, and the paper, header and
footer its PDF gets. It is a task article under the [viewer](../README.md); the
document file in general is on [Writing a document](../writing-a-document/README.md).

## One file or chapters

The smallest doc is one Markdown file, with no document file at all:

<Terminal>

```
$ devpage design.md
$ devpage pdf design.md
```

</Terminal>

It is titled by its `# heading` and printed with the default PDF settings.

A longer doc is split into **chapters**, one Markdown file each, listed in
order in a document file:

<FileTree>

- design/sync/
  - devpage.yml — the doc: its title and the chapters in order
  - context.md — chapter 1
  - design.md — chapter 2
  - rollout.md — chapter 3

</FileTree>

```yaml
kind: doc
title: Sync design
chapters:
  - context.md
  - design.md
  - rollout.md
```

The chapters are read as one page, in the order listed. Reordering them is
moving a line; nobody edits one huge file. Each chapter starts with its own
`# heading`, which becomes a chapter heading in the doc; `title` is the doc's
name, shown above the first chapter, in the tab and in the PDF's metadata. A
doc made from one Markdown file has no separate title: its `# heading` is the
title. A
chapter can be any Markdown file in the served folder, so one shared chapter — a
glossary, a context section — can appear in several docs. A chapter's links
and images are relative to the chapter's own file, wherever its folder is, as
they are on disk.

## The outline

Beside the text, the doc shows its **outline**: each chapter's heading and the
`##` headings under it. It stays in view as the reader scrolls and highlights
the section they are in; clicking an entry scrolls there. The outline is the
doc's table of contents — there is no other one to write. On a narrow screen it
moves above the text.

## Links between chapters

Write links between chapters as links between their files, as you would in the
repository:

```markdown
The rollout is in [three steps](rollout.md#steps).
```

In the doc, that link scrolls to the *Steps* heading of the rollout chapter.

| In the files | In a doc of several chapters |
| --- | --- |
| `## Steps` in `rollout.md` | `#rollout--steps` |
| `## Risks` in `context.md` and in `rollout.md` | `#context--risks` and `#rollout--risks` |
| the start of `rollout.md` | `#rollout` |

In a doc of more than one chapter, a heading's id is its chapter's file name,
without `.md`, then `--`, then the heading's own id — `rollout--steps` — so two
chapters can both have a `## Risks` section and links to each still land in the
right one; a link to a chapter file without a heading lands on the chapter's
start. A doc of one chapter keeps its headings' own ids. Links between
chapters, and `#heading` links within one, are rewritten to those ids when the
doc renders. A link from outside the doc to a chapter file opens that file on
its own, as a page; link to the doc's document file to open the doc.

To link from outside the doc to a place in it, link to its document file with
the id the doc renders: `design/sync/devpage.yml#rollout--steps` for a heading,
`design/sync/devpage.yml#rollout` for the start of a chapter. In a doc of one
chapter, use the heading's own id. These fragments are
[checked](../checking-links/README.md) like any other.

## On paper

A doc prints to PDF with `devpage pdf` ([Printing to PDF](../pdf/README.md)),
or with the browser's own print. Its `pdf` field sets the paper and what is
printed above and below every page:

```yaml
kind: doc
title: Sync design
chapters: [context.md, design.md, rollout.md]
pdf:
  paper: Letter                         # A4 (default) or Letter
  header: Sync design — draft           # default: none
  footer: "{page} / {pages}"            # default: "{page} / {pages}"
```

`{page}` is the page's number and `{pages}` the count. On every page:

<div style="max-width:22rem;margin:1rem auto;border:1px solid var(--border);border-radius:8px;padding:0.6rem 1rem;font-size:0.8rem;color:var(--muted);box-shadow:0 6px 18px -12px color-mix(in srgb, var(--text) 40%, transparent)">
<div style="text-align:center">Sync design — draft</div>
<div style="margin:0.8rem 0;height:6rem;background:repeating-linear-gradient(var(--surface) 0 0.5rem, transparent 0.5rem 1rem)"></div>
<div style="text-align:center">3 / 12</div>
</div>

<Callout title="Only on paper">
Page numbers, header and footer exist only on paper — the doc in the browser is
one continuous page.
</Callout>

Every field of `pdf` is optional; the exact contract is in the
[configuration reference](../configuration-reference/README.md#doc).

## Comments and problems

Comments on a doc attach to the chapter file the text came from, so they
survive a reordering ([Comments](../comments/README.md)). A missing chapter,
or a broken link in any chapter, is listed at the top of the doc while you
write ([Checking links](../checking-links/README.md)).