forked from fastn-stack/ftd.dev
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathp1-grammar.ftd
125 lines (76 loc) · 3.57 KB
/
p1-grammar.ftd
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
/-- ft-core.concept:
-- ft.page-with-toc: `ftd::p1` grammar
toc: $config.doc-toc
sub-sections: $config.doc-header
-- ft.markdown:
`ftd` is based on a low-level grammar called `ftd::p1` grammar.
-- ft.h1: `section`
A `ftd::p1` file is composed of "sections". A section looks like this:
-- ft.code: an `ftd::p1` file with two sections
lang: ftd
\-- some section: the caption of the section
header-1: some header value
hello: world
the body of the first section
\-- something:
yo: 42
-- ft.markdown:
Each section starts with `-- `.
The section has these properties:
-- ft.h2: `section name`
The section name is the only **mandatory parameter** for a section. Name starts
after `-- `, and ends with the first `:`. Trailing `:` is mandatory.
In our example, the name of the first section is `some section`, and the second
section's name is `something`.
Section name contains alphanumeric characters, underscores, space, dots(`.`),
hash(`#`), and hyphens(`-`). Colon terminates the section name.
Leading and trailing whitespaces are not considered part of the section name.
-- ft.h2: `section caption`
What comes after `:` in the section line, till the end of the first line is called
the `caption` of the section.
The `caption` is optional.
In our example, the first section's caption is "the caption of the section", and
the second section does not have a caption.
Leading and trailing whitespaces are not considered part of the caption.
-- ft.h2: `section headers`
After the "section line" (the first line that starts with `-- `, zero or more
section headers can be passed. In our example, the first section has two headers,
`header-1` and `hello`, with values `some header value` and `world` respectively.
An empty newline or the start of a new section (or `sub-section` described below)
marks the end of the headers.
Leading and trailing whitespaces of both header name and header value are ignored.
-- ft.h2: `section body`
After the first empty line that comes after the section header, till the start
of next section (or `sub-section`) is considered the body of the section.
The body is optional.
Leading and trailing newlines are not considered part of the body.
-- ft.h1: `sub-section`
A section can contain zero or more `sub-sections`:
-- ft.code:
lang: ftd
\-- some-section:
optional body of "some-section"
\--- sub-section-1: yo yo
sub-section-header-1: 111
\--- lalala:
this one has a body
-- ft.markdown:
`sub-section` starts with `--- `. If `section` has `body`, body comes before any
of the `sub-section`s.
The sub-section has exactly the same properties as a section, `sub-section name`,
optional `caption`, zero or more headers, and an optional body.
In our example, `some-section` `section` has two `sub-section`s, with names
`sub-section-1` and `lalala` respectively. The first one has a caption, `yo yo`,
and the second doesn't. First `sub-section-1` has one header, and no body, `lalala`
has no header but has a body: `this one has a body`.
-- ft.h1: Philosophy, and why there is no `sub-sub-section`
Check out our [philosophy guide](philosophy/) to understand why we
have taken some of these decisions.
-- ft.h1: Programmatic Access
`ftd::p1` module in `ftd` crate can be used to read `ftd.p1` files. Wrappers of
this crate in Python and other programming languages would hopefully come soon.
-- ft.h2: File Extension
Each user of `ftd::p1` should come up with their own extension, but `.p1` is an
extension which can be used by convention in some cases.
Also consider using `ftd` itself, instead of this low-level library, this library
should only be used as a fallback.