Burrow is to gopherholes as static site builders are to websites.
Burrow is a static site generator, but for gopherholes. A gopherhole is a place in gopherspace accessed through the Gopher protocol).
I made my gopherhole with burrow, so it's an example:
- gopher://gopher.someodd.zip:7071/
- https://github.com/someodd/personal-gopherhole
- This functional example uses this repo's Docker config, allow me to push to the above repo, and the repo that is used to build my gopherhole (Docker setup is a git + gopher server)
There's a .deb (Ubuntu, Debian) available in the releases.
Written in Haskell. If you're looking for very similar software, with coincidentally the exact same name, please check out James Tomasino's Burrow.
You should know these terms:
- gopherhole
- gopherhole project
- gophermap/menu
- gopherspace
A "gopherhole project" is simply a directory that looks like this:
╭━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╮
┃ ⚘ PROJECT ROOT ⚘ ┃
┃ ┣━━ 📂 data/ ┃
┃ ┃ ┣━━ 📂 fonts/ [BMF fonts] ┃
┃ ┃ ┗━━ 📜 burrow.toml [Main config] ┃
┃ ┣━━ 📂 burrowsrc/ [Gopherhole content] ┃
┃ ┗━━ 📂 templates/ [Reusable document bits] ┃
╰━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╯
Note that you can turn this gopherhole project into a git repo... work with Docker...
The software does change directory to the project root and assume project root as the
path that some things are relative to. By default the project root is assumed to be the
directory containing data/burrow.toml (like when you point to it with --config).
All of this "compiles" to a specified output directory, to be served via the Gopher Protocol.
Perhaps the most important file to look over and change yourself. Rules for building the gopherhole project, but also for serving a gopherhole.
Any relative paths are assumed to be relative to the project root.
ASCII art fonts in .bmf format (Burrow M [I forgot] Font). These are currently used when
rendering headers from Markdown files, but I imagine soon I'll make a function so you can
arbitrarily make ASCII art text.
.bmf font spec is simple: on one line is a character you wish to represent, followed by the
ASCII art for the character. Each line for the character must be of the same length. Each
character in the font must be of the same number of lines. Separate character definitions
with blank lines (\n\n).
Re-usable document bits. You can use these bits like macros, to:
- jam some file you wrote inside of a template
- include some template into a file you wrote
You can call upon templates using Frontmatter, but also Moustache.
All the files to be served from your gopherhole, which burrow will either parse or copy. Use whatever directory structure in there.
The rules for parsing a regular text or Markdown file in a gopherholeproject, into either (for gopherspace) a regular text file or a gophermap/menu, are configured like so:
- In
burrow.toml - In the file's Frontmatter: this should override everythinge else
- The file's extension
You may want to read the section(s) on Frontmatter and templating for these files as well
and reading burrow.toml.
This repo contains an example gopherhole project, run this command and then visit
localhost:7070 in gopher (make sure gopher is installed):
burrow serve --config data/burrow.toml --watch
gopher -p "/" localhost 7070
Try editing the files in burrowsrc/ and revisiting the gopherhoole.
There are many different Gopher Protocol clients, my favorite GUI client is Lagrange (Linux, Mac, iOS, Android, more?)--try using it to visit gopher://localhost:7070/.
For an actual production server and even for local testing you may want to check this
project's Docker configuration in docker/, there's a README.md to help you get
started. It has some neat devops-type features.
You can download a binary from the releases page.
- Parse markdown, using commonmark
- Config-based parser, server, and other behavior:
burrow.toml - Front matter
- Mustache templating with extended features
- Blogging/phlogging
- ASCII-art font system
.gophermapsupport, also this is a--spacecookieand burrow setting (which files to make into the main menu for the directory, similar toindex.htmlfor web)
Jekyll-like front matter support. You can tag posts for a phlog, control the rendering process for the file, and more, all through the front matter of the file.
Here's an example of various front matter entries specifically supported by Burrow:
---
published: 2021-06-01T05:44
updated: June 13th at 10pm
author: Some Author's Name
type: post
variables: {"someVariable": "Some text to replace someVariable.", "foo": "bar"}
skipMustache: false
skipMarkdown: false
parentTemplate: post
renderAs: menu
---
Here's the content of my post that supports Markdown and Mustache.Use Mustache for templating. In addition to simple templating, it also comes pre-loaded with some functions for ASCII-art-ifying files.
There are built in lambdas for your convenience:
{{#columnate2}}this text will be justified and broken up like a newspaper{{/columnate2}}{{#justify}}this text will be justified{{/justify}}{{#justify2}}this text will be justified using a different algorith, I think{{/justify2}}
I imagine more is to come and hopefully even more beautiful ASCII art can be had. I encourage people, here most of all, to make open source contributions.
Indexes will be generated as gophermaps for posts which are tagged and have all
the required front matter (like published, title, and type: post).
Atom feeds will be generated for each index (tag indexes, the main feed, and tag summaries).
This software has primarily been tested with
spacecookie (Gopher server). Although now
techically using an integrated fork of that software in Burrow. You may want to look at
my spacecookie Docker repo. Currently,
Burrow relies heavily on the .gophermap behavior outlined in these documents:
Other good things to read about and know:
- mustache
- CommonMark: a great Markdown standard (used by GitHub, Reddit, Stack Overflow)
- You should know about the Gopher protocol
Turn this:
---
title: Example phlog post
published: 2021-06-12
updated: June 13th, 2021 at 10pm
author: someodd
type: post
tags: foo bar
variables: {"someVariable": "Some text to replace someVariable.", "foo": "bar"}
parentTemplate: post.txt
renderAs: menu
---
This is an example phlog post.
{{ someVariable }}
## Columnate Example
{{#columnate2}}
The Gopher protocol /ˈɡoʊfər/ is a communications protocol designed for distributing, searching, and retrieving documents in Internet Protocol networks. The design of the Gopher protocol and user interface is menu-driven, and presented an alternative to the World Wide Web in its early stages, but ultimately fell into disfavor, yielding to the Hypertext Transfer Protocol (HTTP) The Gopher ecosystem is often regarded as the effective predecessor of the World Wide Web.[1]
The protocol was invented by a team led by Mark P. McCahill[2] at the University of Minnesota. It offers some features not natively supported by the Web and imposes a much stronger hierarchy on the documents it stores. Its text menu interface is well-suited to computing environments that rely heavily on remote text-oriented computer terminals, which were still common at the time of its creation in 1991, and the simplicity of its protocol facilitated a wide variety of client implementations. More recent Gopher revisions and graphical clients added support for multimedia.[citation needed] Gopher was preferred by many network administrators for using fewer network resources than Web services.[3]
Gopher's hierarchical structure provided a platform for the first large-scale electronic library connections.[4] The Gopher protocol is still in use by enthusiasts, and although it has been almost entirely supplanted by the Web, a small population of actively-maintained servers remains.
{{/columnate2}}
[some link](/some-menu)Into this:
══════════════════════════════════════════════════════════════════════════════════════════
██████████████████████████████████████████████████████████████████████████████████████████
█ ██ █ ██▀ ▀██ █ ██ ▀██ ████ ███████ ▀██ █ ██ ████▀ ▀██▀ ███████ ▀██▀ ▀██▀ ██ █
█ ████ █ ██ █ ██ ██ █ ██ ████ █████████ █ ██ █ ██ ████ █ ██ █████████ █ ██ █ ██ █████ ██
█ ███ ███ ▄ ██ ██ ▄██ ████ ███████ ▄██ ██ ████ █ ██ █\███████ ▄██ █ ██ ▀███ ██
█ ████ █ ██ █ ██ █ ██ ████ ████ █████████ ████ █ ██ ████ █ ██ █ ███████ ████ █ ████ ███ ██
█ ██ █ ██ █ ██ █ ██ ████ ██ ███████ ████ █ ██ ██▄ ▄██▄ ███████ ████▄ ▄██ ▄███ ██
██████████████████████████████████████████████████████████████████████████████████████████
══════════════════════════════════════════════════════════════════════════════════════════
Posted: 2021-06-12
Updated: 2021-06-13
Author: someodd
Tags: foo, bar
This is an example phlog post.
Some text to replace someVariable
═════════════════════════════════════════════════════════════════════════════════════
█████████████████████████████████████████████████████████████████████████████████████
█ ██▀ ▀██ ████ █ ██ █ ██ ████▀ ▀██ ██ ███████ ██ █ ██▀ ▀██ █ ██ ▀██ ████ █
█ ████ █ ██ ████ █ ██ ██ ▀██ █ ███ ███ █████████ ████ █ ██ █ ██ ██ █ ██ ████ ███
█ ████ █ ██ ████ █ ██ ██ █ ██ ▄ ███ ███ ███████ ███ ███ ▄ ██ ██ ▄██ ████ █
█ ████ █ ██ ████ █ ██ █ ██ █ ██ █ ███ ███ █████████ ████ █ ██ █ ██ █ ██ ████ ████ ███
█ ██▄ ▄██ ██ ██ █ ██ █ ██ █ ███ ███ ███████ ██ █ ██ █ ██ █ ██ ████ ██ █
█████████████████████████████████████████████████████████████████████████████████████
═════════════════════════════════════════════════════════════════════════════════════
The Gopher protocol /ˈɡoʊfər/ is a │ interface is well-suited to computing
communications protocol designed for │ environments that rely heavily on
distributing, searching, and │ remote text-oriented computer
retrieving documents in Internet │ terminals, which were still common at
Protocol networks. The design of the │ the time of its creation in 1991, and
Gopher protocol and user interface is │ the simplicity of its protocol
menu-driven, and presented an │ facilitated a wide variety of client
alternative to the World Wide Web in │ implementations. More recent Gopher
its early stages, but ultimately fell │ revisions and graphical clients added
into disfavor, yielding to the │ support for multimedia.[citation
Hypertext Transfer Protocol (HTTP) The │ needed] Gopher was preferred by many
Gopher ecosystem is often regarded as │ network administrators for using fewer
the effective predecessor of the World │ network resources than Web
Wide Web.[1] The protocol was invented │ services.[3] Gopher's hierarchical
by a team led by Mark P. McCahill[2] │ structure provided a platform for the
at the University of Minnesota. It │ first large-scale electronic library
offers some features not natively │ connections.[4] The Gopher protocol is
supported by the Web and imposes a │ still in use by enthusiasts, and
much stronger hierarchy on the │ although it has been almost entirely
documents it stores. Its text menu │ supplanted by the Web, a small
population of actively-maintained
servers remains.
0some link /some-menu
bar