https://github.com/tdemin/gmnhg
Hugo-to-Gemini Markdown converter
https://github.com/tdemin/gmnhg
converter gemini go golang hugo markdown
Last synced: about 1 year ago
JSON representation
Hugo-to-Gemini Markdown converter
- Host: GitHub
- URL: https://github.com/tdemin/gmnhg
- Owner: tdemin
- License: gpl-3.0
- Created: 2021-07-31T21:50:54.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-05-21T14:11:59.000Z (about 3 years ago)
- Last Synced: 2024-05-20T23:03:36.429Z (about 2 years ago)
- Topics: converter, gemini, go, golang, hugo, markdown
- Language: Go
- Homepage:
- Size: 139 KB
- Stars: 27
- Watchers: 4
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
- awesome-gemini - md2gmn - renders Markdown text to Gemini pages. (Tools / Gemtext converters)
README
# Hugo-to-Gemini converter
[](https://pkg.go.dev/github.com/tdemin/gmnhg)
[](https://goreportcard.com/report/github.com/tdemin/gmnhg)
[](https://github.com/tdemin/gmnhg/actions/workflows/docker.yml)
This repo holds a converter of Hugo Markdown posts to
[text/gemini][Gemtext] (also named Gemtext in this README). The
converter is supposed to make people using [Hugo](https://gohugo.io)'s
entrance to [Project Gemini][Gemini], the alternate web, somewhat
simpler.
[Gemini]: https://gemini.circumlunar.space
[Gemtext]: https://gemini.circumlunar.space/docs/specification.html
The renderer uses the [gomarkdown][gomarkdown] library for parsing
Markdown. gomarkdown has a few quirks at this time, the most notable one
being unable to parse links/images inside other links.
At this time, gmnhg can convert these Markdown elements to Gemtext:
* paragraphs, converting them to soft wrap as per Gemini spec p. 5.4.1;
* inline text formatting (bold, emphasis, strikethrough, code,
subscript, superscript), which stays in the text to preserve stylistic
context;
* headings;
* blockquotes;
* preformatted blocks;
* tables, displayed as ASCII preformatted blocks;
* lists (as Gemini doesn't allow lists of level >= 2, those will be
reflected with an extra indentation level): ordered, numbered,
definition;
* links and images, rendered as Gemtext links (inline links are rendered
after their parent paragraph or other block element in a links block
sorted by element type);
* footnotes, rendered as paragraphs;
* horizontal rules.
The renderer will also treat lists of links and paragraphs consisting of
links only the special way: it will render only the links block for
them.
To get a better idea of how source Markdown looks like after the
conversion to Gemtext, see [testdata](testdata) directory.
[gomarkdown]: https://github.com/gomarkdown/markdown
## gmnhg
This program converts Hugo Markdown content files from `content/` in
accordance with templates found in `gmnhg/` to the output dir. It
also copies static files from `static/` to the output dir.
For more details about the rendering process, see the
[doc](cmd/gmnhg/main.go) attached to the program.
```
Usage of gmnhg:
-output string
output directory (will be created if missing) (default "output/")
-working string
working directory (defaults to current directory)
```
## md2gmn
This program reads Markdown input from either text file (if `-f
filename` is given), or stdin. The resulting Gemtext goes to stdout.
```
Usage of md2gmn:
-f string
input file
```
md2gmn is mainly made to facilitate testing the Gemtext renderer but
can be used as a standalone program as well.
## Site configuration
gmnhg will pick up some attributes such as site title, base URL, and
language code from your Hugo configuration file (`config.toml`,
`config.yaml`, or `config.json`). Presently these are used in the
default RSS template.
gmnhg provides a way to override these attributes by defining a
`gmnhg` section in the configuration file and nesting the attributes
to override underneath this section. Presently you can override both
`baseUrl` and `title` in this manner.
For example, you could add the following to your `config.toml` to
override your `baseUrl`:
```
[gmnhg]
baseUrl = "gemini://mysite.com"
```
This is recommended, as it will ensure that RSS links on your Gemini
site use the correct URL.
## License
This program is redistributed under the terms and conditions of the GNU
General Public License, more specifically version 3 of the License. For
details, see [COPYING](COPYING).