108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
[](https://goreportcard.com/report/github.com/n0x1m/hugoext)
|
|
[](https://godoc.org/github.com/n0x1m/hugoext)
|
|
|
|
# hugoext
|
|
|
|
Utility to parse the hugo config file and recreate the same file structure for content files through
|
|
an arbitrary output pipe extension for processing.
|
|
|
|
Hugo parses primarily markdown files and go templates. The initial motivation for this utility was
|
|
to enable the same tools to publish a Gemlog version of a hugo blog to make it accessible as Gemtext
|
|
via the Gemini protocol.
|
|
|
|
**NOTE**: this is rather minimal and only has one use case for now, many edge cases may not be covered.
|
|
|
|
**Features**
|
|
- reads hugo `.toml` file for section output formats
|
|
- supports an arbitrary document processor, any program that supports UNIX pipes
|
|
- ugly urls, note that I have not tested this much with links, pretty urls recommended
|
|
- append section listings to section pages, optionally on root
|
|
- supports with and without drafts from config
|
|
- composable with other tools
|
|
|
|
TODOs:
|
|
- cleanup long main
|
|
- gemrss?
|
|
|
|
To illustrate what this program does, run the following in the hugo directory.
|
|
|
|
```
|
|
hugoext -ext txt -pipe=""
|
|
```
|
|
|
|
The markdown files from `./content` will be written as `.txt` files to the `./public` directory. We
|
|
can add a processor that converts markdown to a different extension and output the same directory
|
|
layout as hugo does. Here, when the selected processor is blank, markdown files will be copied
|
|
unmodified.
|
|
|
|
## Example Use
|
|
|
|
Using the [md2gmi](https://github.com/n0x1m/md2gmi) command line utility to convert markdown to
|
|
gemtext. Executed from the hugo directory:
|
|
|
|
```
|
|
hugoext -ext gmi -pipe md2gmi
|
|
```
|
|
|
|
It abides the hugo section config in `[permalinks]` but only uses the content subdirectory to
|
|
determine the section. An example section config in hugo looks like this:
|
|
|
|
```
|
|
[permalink]
|
|
posts = "/posts/:year/:month:day/:filename"
|
|
snippets = "/snippets/:filename"
|
|
page = ":filename"
|
|
```
|
|
|
|
### Installation
|
|
|
|
```
|
|
go install github.com/n0x1m/hugoext@latest
|
|
```
|
|
|
|
To use the gemini file server and markdown to gemtext converter in the examples below, also install
|
|
these:
|
|
|
|
```
|
|
go install github.com/n0x1m/md2gmi@latest
|
|
go install github.com/n0x1m/gmifs@latest
|
|
```
|
|
|
|
### Development
|
|
|
|
To test the extension in a similar fashion to the hugo workflow, use a server to host the static
|
|
files. Here an example for a Gemlog using [gmifs](https://github.com/n0x1m/gmifs) in a makefile:
|
|
|
|
```makefile
|
|
serve:
|
|
hugoext -ext gmi -pipe md2gmi
|
|
gmifs -autoindex
|
|
```
|
|
|
|
hugoext pipes the input through the `md2gmi` extension and writes the output file tree. We then
|
|
spawn `gmifs` to serve it on `gemini://localhost` with auto indexing enabled.
|
|
|
|
### Production
|
|
|
|
I have a makefile target in my hugo directory to build and publish html and gemtext content:
|
|
|
|
```makefile
|
|
build:
|
|
hugo --minify
|
|
hugoext -ext gmi -pipe md2gmi
|
|
|
|
publish: build
|
|
rsync -a -P --delete ./public/ dre@nox.im/var/www/htdocs/nox.im/
|
|
```
|
|
|
|
The output directory for both hugo and hugoext is `./public`. It's ok to mix the two into the same
|
|
file tree as each directory will contain an `index.html` and an `index.gmi` file.
|
|
|
|
## Acknowledgements & Attribution
|
|
|
|
For config parsing and compatibility, this repo uses the latest hugo source tree as the functions are all
|
|
exported. For markdown and metadata parsing of hugo content files, I've extracted some code from
|
|
[hugo@v0.49.2](https://github.com/gohugoio/hugo/tree/v0.49.2/) tree and made them importable in the
|
|
local [hugo](./hugo) package. The version had required frontmatter, metadata and section permalink
|
|
parsers still available in well isolated functions, so I didn't need to recreate them.
|