Skip to content

docs(ref): Specify frontmatter #1974

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

docs(ref): Specify frontmatter #1974

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
- [Input format](input-format.md)
- [Keywords](keywords.md)
- [Identifiers](identifiers.md)
- [Frontmatter](frontmatter.md)
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not stable yet: rust-lang/rust#136889

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put this under "Lexical structure" because this shebang is there

- [Comments](comments.md)
- [Whitespace](whitespace.md)
- [Tokens](tokens.md)
Expand Down
1 change: 1 addition & 0 deletions src/crates-and-source-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ r[crate]
r[crate.syntax]
```grammar,items
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aside: it took me a while before I found the appropriate documentation for this.

I quickly went to CONTRIBUTING.md but skipped over the link to the authoring page because it was at the end of the intro. I skimmed the sections until I found "Adding Documentation" which seemed to describe my situation but I found no link.

Eventually I found authoring.md and thankfully I read thoroughly enough to notice the "Grammar" section at the bottom. At that point, I was mostly able to interpret the results to figure out what I needed (e.g. the limitations of ~, what to search for to understand how to do footnotes).

As noted at https://github.com/rust-lang/reference/pull/1974/files#r2292171963, it doesn't really give a style guidance on casing.

@root Crate ->
FRONTMATTER?
InnerAttribute*
Item*
Comment on lines +7 to 9
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used comments as my guide which were mostly SCREAMING_CASE. Unsure when things should be SCREAMING_CASE vs UpperCamelCase.

Comment on lines +7 to 9
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Despite shebang's not having being here, I assumed I should put FRONTMATTER here

```
Expand Down
42 changes: 42 additions & 0 deletions src/frontmatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
r[frontmatter]
# Frontmatter

r[frontmatter.syntax]
```grammar,lexer
FRONTMATTER ->
FRONTMATTER_FENCE INFOSTRING? LF
(FRONTMATTER_LINE LF )*
FRONTMATTER_FENCE[^matched-fence] LF

FRONTMATTER_FENCE -> `---` `-`*

INFOSTRING -> XID_Start ( XID_Continue | `-` | `.` )*

FRONTMATTER_LINE -> (~INVALID_FRONTMATTER_LINE_START (~INVALID_FRONTMATTER_LINE_CONTINUE)*)?

INVALID_FRONTMATTER_LINE_START -> (FRONTMATTER_FENCE[^escaped-fence] | LF)

INVALID_FRONTMATTER_LINE_CONTINUE -> LF
```

[^matched-fence]: The closing fence must have the same number of `-` as the opening fence
[^escaped-fence]: A `FRONTMATTER_FENCE` at the beginning of a `FRONTMATTER_LINE` is only invalid if it has the same or more `-` as the `FRONTMATTER_FENCE`

Frontmatter is an optional section for content intended for external tools without requiring these tools to have full knowledge of the Rust grammar.

r[frontmatter.document]
Frontmatter may only be preceded by a [shebang] and whitespace.

r[frontmatter.fence]
The delimiters are referred to as a "fence."
The opening and closing fences must be at the start of a line.
They must be a matching pair of three or more hyphens (`-`).

r[frontmatter.infostring]
Following the opening fence may be an infostring for identifying the intention of the contained content.
An infostring may be preceded by non-newline whitespace.

r[frontmatter.body]
The body of the frontmatter may contain any content except for a line starting with as many or more hyphens (`-`) than in the fences.

[shebang]: input-format.md#shebang-removal