A Hugo theme to convert a Hugo site to Gopher and/or Gemini with the purpose of maintaining between one and three sites (a static web site, a Gopher hole, and a Gemini capsule). Each site may have different content.
This theme is expected to be used as an additional theme. While, by default, your main theme will generate the site in the public
folder, this additional theme will generate in public-gg
. This requires two distinct executions of hugo
, namely one for your regular theme, and one for this theme. There are no changes or side effects to your original Hugo site or files.
There are few use cases for this theme:
- A person with a current Hugo generated site that want to have presence in Gopher space or/and in Gemini space, while maintaining the original web site using Hugo. In this situation the person can use Hugo to maintain all the sites (the web site, the Gopher hole and the Gemini capsule). Most content will be common between them, but other content may be specific to one or two of the sites.
- A person that wants to use Hugo to generate and maintain a Gemini capsule or Gopher hole.
- A person that wants to migrate a current Hugo web site to a Gemini capsule or a Gopher hole.
You may find my basic step by step on how to use this tool useful to understand this page. In addition you may find the Gopher-and-Gemini-Walker tool useful to verify the generated Gopher hole and/or the Gemini capsule before deploying them.
- Menu
- Social media links
- Do not generate HTML or RSS
- Automatic conversion of a Hugo site to a Gopher hole
- Automatic conversion of a Hugo site to a Gemini capsule
In most cases, you will already have Hugo installed and have already a theme for your web site. You will install this theme as an additional complementary theme (while maintaining your current theme). However, if you have not installed hugo follow the instructions at quick start.
To add this theme to your current hugo site, just do:
~$ git clone https://github.com/mkamarin/Hugo-2-Gopher-and-Gemini.git
For more information, see Hugo docs. For upgrades, just do:
~$ git submodule update --remote --merge
- You need to copy the
config-gg.toml
file to the main folder of your hugo site and edit it to adjust it to your situation. Now you have two distinct config files, namely one for your main theme (config.toml
) and one for this theme (config-gg.toml
).
You may want some pages to be treated different when generating them for Gopher or Gemini. In those cases, you can add to the page front matter some of the flags described in Hugo-2-Gopher-and-Gemini/archetypes/default.md
.
- If you plan to have content that is specific to Gopher and/or Gemini, you may want to use a naming convention for those posts. For example, you may name those posts
<name>-gg.md
and write them in a way that will look nice in Gopher and/or Gemini. In that case, you want to add the following line to your mainconfig.toml
file:
ignoreFiles = ["-gg.md$"]
Then, when you want to create content that should only be in Gopher and/or Gemini, you will create the markdown file as follows:
~$ hugo new posts/name-gg.md
- You need to create an empty folder called
layouts-gg
. This is done to avoid hugo from using the content in your mainlayouts
folder.
~$ mkdir layouts-gg
-
The
public-gg
folder will have two sub-folders, one for the Gopher hole namedpublic-gg/gopher
and one for the Gemini capsule namedpublic-gg/gemini
. There are two ways you can generate thepublic-gg
folder:- Execute
hugo2gg.py
located in this theme folder undersrc
. In most cases, the default options will work fine. You can see all the options by executinghugo2gg.py --help
. Based on the options,hugo2gg.py
will execute hugo as the first step of the conversion. So, in most cases, you just want to execute it from the main folder of your hugo site as:
- Execute
~$ themes/Hugo-2-Gopher-and-Gemini/src/hugo2gg.py
* If you want to execute hugo manually before executing `hugo2gg.py`, you can do as follows:
~$ hugo --config config-gg.toml --destination public-gg --layoutDir layouts-gg --disableKinds sitemap
~$ themes/Hugo-2-Gopher-and-Gemini/src/hugo2gg.py --no-hugo
- Now you can check the generated files. By default, the Gopher hole will be in
public-gg/gopher
and the Gemini capsule inpublic-gg/gemini
. You may want to browse those directories using the Gopher-and-Gemini-Walker tool before deploying them to your hosting environment.
Usage:
hugo2gg.py [flags]
Flags:
-p, --path <path> Path of the site to be converted (default to public-gg)
-g, --gopher <path> Gopher output folder (default to public-gg/gopher)
-G, --gemini <path> Gemini output folder (default to public-gg/gemini)
-e, --empty <path> Path of empty folder (default to layouts-gg)
-l, --last <path> Path for last build folder (default to public-gg-sav)
-b, --base <path> Rebase all Gopher absolute links to <path>
-B, --Base <path> Rebase all Gemini absolute links to <path>
-c, --config <file> Name of the hugo config file (default to config-gg.toml)
-M, --map <file> File with mapping of labels to links (default to hugo2gg.map)
-t, --type <type> type of output to be generated (default to none)
<type> can be:
all Generate both gopher and gemini sites
gopher Generate only the gopher hole
gemini Generate only the gemini capsule
-k, --keep Keep processed temporary files for debugging purposes
-m, --max-line <num> Max lenght of gophermap lines (default 70 but some prefer 67)
-f, --full-line Forces each line in the gophermap to be fully compliant
(overrides fullLine and textChar in config-gg.toml)
-n, --no-hugo Do not run hugo. Remember to run hugo before
-w, --white-lines <num> Indicate the max number of empty lines (default 1)
-h, --help Prints this help
-v, --verbose Produces verbose stdout output
The script src/fixup.sh
is useful to post-process the generated Gopher hole or Gemini capsule before deployment. Although, src/hugo2gg.py
implements the same functionality, in my workflow I have found it easier to use src/fixup.sh
.
This script is useful to re-base a Gemini capsule or Gopher hole. Meaning, changing all the absolute links (links that start with "/") to add a base directory.
In addition, this script can add the correct host and port to a gophermap. Therefore, making each line in the gophermap comply with the four tabs expected by some Gopher servers.
GPLv3
-
Use textChar: false if you are going to use fixup.sh, or you'll get doble "i" in your gophermap.
-
Help from the scripts: add -h when executing.
-
Copy the contents from layouts to layouts-gg, so it transforms the files.
-
Rebase with hugo2gg.py doesn't work (yet?), use fixup.sh