~erock/pico

ref: 90951e09568b61d17747a4a76036f2a876fe3f3e pico/lists/html/spec.page.tmpl -rw-r--r-- 7.8 KiB
90951e09Eric Bower fix(lists): wrong anchor links a month ago
                                                                                
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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
{{template "base" .}}

{{define "title"}}specification -- {{.Site.Domain}}{{end}}

{{define "meta"}}
<meta name="description" content="a specification for lists" />
{{end}}

{{define "body"}}
<header>
    <h1 class="text-2xl">Plain text list</h1>
    <h2 class="text-xl">Speculative specification</h2>
    <dl>
        <dt>Version</dt>
        <dd>2022.08.05.dev</dd>

        <dt>Status</dt>
        <dd>Draft</dd>

        <dt>Author</dt>
        <dd>Eric Bower</dd>
    </dl>
</header>
<main>
    <section id="overview">
        <p>
            The goal of this specification is to understand how we render plain text lists.
            The overall design of this format is to be easy to parse and render.
        </p>

        <p>
            The format is line-oriented, and a satisfactory rendering can be achieved with a single
            pass of a document, processing each line independently. As per gopher, links can only be
            displayed one per line, encouraging neat, list-like structure.
        </p>

        <p>
            Feedback on any part of this is extremely welcome, please email
            <a href="mailto:{{.Site.Email}}">{{.Site.Email}}</a>.
        </p>

        <p>
            The source code for our parser can be found
            <a href="https://git.sr.ht/~erock/pico/tree/main/item/lists/parser.go">here</a>.
        </p>
    </section>

    <section id="parameters">
        <h2 class="text-xl">
            <a href="#parameters" rel="nofollow noopener">#</a>
            Parameters
        </h2>
        <p>
            As a subtype of the top-level media type "text", "text/plain" inherits the "charset"
            parameter defined in <a href="https://datatracker.ietf.org/doc/html/rfc2046#section-4.1">RFC 2046</a>.
            The default value of "charset" is "UTF-8" for "text" content.
        </p>
    </section>

    <section id="line-orientation">
        <h2 class="text-xl">
            <a href="#line-orientation" rel="nofollow noopener">#</a>
            Line orientation
        </h2>
        <p>
            As mentioned, the text format is line-oriented. Each line of a document has a single
            "line type". It is possible to unambiguously determine a line's type purely by
            inspecting its first (3) characters. A line's type determines the manner in which it
            should be presented to the user. Any details of presentation or rendering associated
            with a particular line type are strictly limited in scope to that individual line.
        </p>
    </section>

    <section id="file-extensions">
        <h2 class="text-xl">
            <a href="#file-extensions" rel="nofollow noopener">#</a>
            File extension
        </h2>
        <p>
            {{.Site.Domain}} only supports the <code>.txt</code> file extension and will
            ignore all other file extensions.
        </p>
    </section>

    <section id="list-item">
        <h2 class="text-xl">
            <a href="#list-item" rel="nofollow noopener">#</a>
            List item
        </h2>
        <p>
            List items are separated by newline characters <code>\n</code>.
            Each list item is on its own line.  A list item does not require any special formatting.
            A list item can contain as much text as it wants.  We encourage soft wrapping for readability
            in your editor of choice.  Hard wrapping is not permitted as it will create a new list item.
        </p>
        <p>
            Empty lines will be completely removed and not rendered to the end user.
        </p>
    </section>

    <section id="hyperlinks">
        <h2 class="text-xl">
            <a href="#hyperlinks" rel="nofollow noopener">#</a>
            Hyperlinks
        </h2>
        <p>
            Hyperlinks are denoted by the prefix <code>=></code>.  The following text should then be
            the hyperlink.
        </p>
        <pre>=> https://{{.Site.Domain}}</pre>
        <p>Optionally you can supply the hyperlink text immediately following the link.</p>
        <pre>=> https://{{.Site.Domain}} microblog for lists</pre>
    </section>

    <section id="nested-lists">
        <h2 class="text-xl">
            <a href="#nested-lists" rel="nofollow noopener">#</a>
            Nested lists
        </h2>
        <p>
            Users can create nested lists.  Tabbing a list will nest it under the list item
            directly above it.  Both tab character `\t` or whitespace as tabs are permitted.
        </p>
        <pre>first item
    second item
        third item
last item</pre>
    </section>

    <section id="images">
        <h2 class="text-xl">
            <a href="#images" rel="nofollow noopener">#</a>
            Images
        </h2>
        <p>
            List items can be represented as images by prefixing the line with <code>=<</code>.
        </p>
        <pre>=< https://i.imgur.com/iXMNUN5.jpg</pre>
        <p>Optionally you can supply the image alt text immediately following the link.</p>
        <pre>=< https://i.imgur.com/iXMNUN5.jpg I use arch, btw</pre>
    </section>

    <section id="headers">
        <h2 class="text-xl">
            <a href="#headers" rel="nofollow noopener">#</a>
            Headers
        </h2>
        <p>
            List items can be represented as headers.  We support two headers currently.  Headers
            will end the previous list and then create a new one after it.  This allows a single
            document to contain multiple lists.
        </p>
        <pre># Header One
## Header Two</pre>
    </section>

    <section id="blockquotes">
        <h2 class="text-xl">
            <a href="#blockquotes" rel="nofollow noopener">#</a>
            Blockquotes
        </h2>
        <p>
            List items can be represented as blockquotes.
        </p>
        <pre>> This is a blockquote.</pre>
    </section>

    <section id="preformatted">
        <h2 class="text-xl">
            <a href="#preformatted" rel="nofollow noopener">#</a>
            Preformatted
        </h2>
        <p>
            List items can be represented as preformatted text where newline characters are not
            considered part of new list items.  They can be represented by prefixing the line with
            <code>```</code>.
        </p>
        <pre>```
#!/usr/bin/env bash

set -x

echo "this is a preformatted list item!
```</pre>
        <p>
            You must also close the preformatted text with another <code>```</code> on its own line. The
            next example with NOT work.
        </p>
        <pre>```
#!/usr/bin/env bash

echo "This will not render properly"```</pre>
    </section>

    <section id="variables">
        <h2 class="text-xl">
            <a href="#variables" rel="nofollow noopener">#</a>
            Variables
        </h2>
        <p>
            Variables allow us to store metadata within our system.  Variables are list items with
            key value pairs denoted by <code>=:</code> followed by the key, a whitespace character,
            and then the value.
        </p>
        <pre>=: publish_at 2022-04-20</pre>
        <p>These variables will not be rendered to the user inside the list.</p>
        <h3 class="text-lg">List of available variables:</h3>
        <ul>
            <li><code>title</code> (custom title not dependent on filename)</li>
            <li><code>description</code> (what is the purpose of this list?)</li>
            <li><code>publish_at</code> (format must be <code>YYYY-MM-DD</code>)</li>
            <li><code>tags</code> (format must be comma delimited: <code>feature, announcement</code>)</li>
            <li>
                <code>list_type</code> (customize bullets; value gets sent directly to css property
                <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-type">list-style-type</a>)
            </li>
        </ul>
    </section>
</main>
{{template "marketing-footer" .}}
{{end}}