Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/abhinav/goldmark-frontmatter
Adds support for YAML and TOML front matter to Markdown documents.
https://github.com/abhinav/goldmark-frontmatter
goldmark markdown
Last synced: 14 days ago
JSON representation
Adds support for YAML and TOML front matter to Markdown documents.
- Host: GitHub
- URL: https://github.com/abhinav/goldmark-frontmatter
- Owner: abhinav
- License: bsd-3-clause
- Created: 2023-03-16T18:41:48.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-21T01:39:22.000Z (26 days ago)
- Last Synced: 2024-10-30T06:27:17.041Z (17 days ago)
- Topics: goldmark, markdown
- Language: Go
- Homepage: https://abhinav.github.io/goldmark-frontmatter/
- Size: 98.6 KB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# goldmark-frontmatter
[](https://pkg.go.dev/go.abhg.dev/goldmark/frontmatter)
[](https://github.com/abhinav/goldmark-frontmatter/actions/workflows/ci.yml)
[](https://codecov.io/gh/abhinav/goldmark-frontmatter)
goldmark-frontmatter is an extension for the [goldmark] Markdown parser
that adds support for parsing YAML and TOML front matter from Markdown documents.
[goldmark]: http://github.com/yuin/goldmark
## Features
- Parses YAML and TOML front matter out of the box
- Allows defining your own front matter formats
- Exposes front matter in via a types-safe API
#### Comparison to goldmark-meta
[yuin/goldmark-meta](https://github.com/yuin/goldmark-meta)
is another extension for goldmark that provides support for frontmatter.
Here's a quick comparison of the two extensions:
| Feature | goldmark-frontmatter | goldmark-meta |
| ------------------------ | -------------------- | ------------- |
| YAML support (`---`) | ✅ | ✅ |
| TOML support (`+++`) | ✅ | ❌ |
| Custom formats | ✅ | ❌ |
| Decode `map[string]any` | ✅ | ✅ |
| Decode type-safe structs | ✅ | ❌ |
| Render as table | ❌ | ✅ |
### Demo
A web-based demonstration of the extension is available at
.
## Installation
```bash
go get go.abhg.dev/goldmark/frontmatter@latest
```
## Usage
To use goldmark-frontmatter, import the `frontmatter` package.
```go
import "go.abhg.dev/goldmark/frontmatter"
```
Then include the `frontmatter.Extender` in the list of extensions
when constructing your [`goldmark.Markdown`].
[`goldmark.Markdown`]: https://pkg.go.dev/github.com/yuin/goldmark#Markdown
```go
goldmark.New(
goldmark.WithExtensions(
// ...
&frontmatter.Extender{},
),
).Convert(src, out)
```
By default, this won't have any effect except stripping the front matter
from the document.
See [Accessing front matter](#accessing-front-matter) on how to read it.
### Syntax
Front matter starts with three or more instances of a delimiter,
and must be the first line of the document.
The supported delimiters are:
- YAML: `-`
For example:
```markdown
---
title: goldmark-frontmatter
tags: [markdown, goldmark]
description: |
Adds support for parsing YAML front matter.
---
# Heading 1
```
- TOML: `+`
For example:
```markdown
+++
title = "goldmark-frontmatter"
tags = ["markdown", "goldmark"]
description = """\
Adds support for parsing YAML front matter.\
"""
+++
# Heading 1
```
The front matter block ends with the same number of instances of the delimiter.
So if the opening line used 10 occurrences, so must the closing.
---------------------------
title: goldmark-frontmatter
tags: [markdown, goldmark]
---------------------------
### Accessing front matter
You can use one of two ways to access front matter
parsed by goldmark-frontmatter:
* [Decode it into a struct with `frontmatter.Data`](#decode-a-struct)
* [Read from document metadata](#read-from-document-metadata)
#### Decode a struct
To decode front matter into a struct,
you must pass in a `parser.Context`
when you call `Markdown.Convert` or `Parser.Parse`.
```go
md := goldmark.New(
goldmark.WithExtensions(&frontmatter.Extender{}),
// ...
)
ctx := parser.NewContext()
md.Convert(src, out, parser.WithContext(ctx))
```
Following that, use `frontmatter.Get` to access a `frontmatter.Data` object.
Use `Data.Decode` to unmarshal your front matter into a data structure.
```go
d := frontmatter.Get(ctx)
var meta struct {
Title string `yaml:"title"`
Tags []string `yaml:"tags"`
Desc string `yaml:"description"`
}
if err := d.Decode(&meta); err != nil {
// ...
}
```
You're not limited to structs here.
You can also decode into `map[string]any` to access all fields.
```go
var meta map[string]any
if err := fm.Decode(&meta); err != nil {
// ...
}
```
However, if you need that, it's easier to
[read it from the document metadata](#read-from-document-metadata).
#### Read from document metadata
You can install the extension with `frontmatter.SetMetadata` mode:
```go
md := goldmark.New(
goldmark.WithExtensions(&frontmatter.Extender{
Mode: frontmatter.SetMetadata,
}),
// ...
)
```
In this mode, the extension will decode the front matter
into a `map[string]any`,
and set it on the [Document](https://pkg.go.dev/github.com/yuin/goldmark/ast#Document).
You can access it with the [Document.Meta method](https://pkg.go.dev/github.com/yuin/goldmark/ast#Document.Meta).
```go
root := md.Parser().Parse(text.NewReader(src))
doc := root.OwnerDocument()
meta := doc.Meta()
```
## License
This software is made available under the BSD3 license.