~skyfaller/maxethics-hugo

#Max Ethics Hugo Theme

Minimalist Hugo theme written for readable HTML. First and primary Hugo theme used by Maximum Ethics

Produces readable HTML and CSS that can be inspected and learned from.
- We eliminate optional HTML when possible, to maintain performance without minification.
Standards compliant: valid HTML and CSS.
Passes accessibility and page speed tests
- Google Lighthouse
- Axe web accessibility
Security: working to improve our Mozilla Observatory score, by avoiding inline CSS and Javascript so we can have a strong Content Security Policy and head off cross-site scripting attacks.
Designed with progressive enhancement in mind.
- Should be usable with Javascript or even CSS disabled. (Images may look huge with CSS disabled, sorry.)
- Tested with all actively maintained open source browser engines, degrading gracefully when a browser lacks a feature:
  - Gecko (Firefox)
  - Blink (Chromium)
  - WebKit (Gnome Web / Nyxt)
  - Goanna (Pale Moon)
  - NetSurf

#Prerequisites

Hugo installed on your machine
A webserver to host your static site from
Git version control software

#Optional

Local installation of Go programming language (in order to install using Hugo Modules)

#Installing

When installing our theme, you must decide whether to use Hugo Modules or not.

#With Hugo Modules

We use Hugo Modules to install and update this theme on our infrastructure, rather than using Git submodules or subtrees (between the two, subtrees might actually be better for the casual user). This does add a dependency of a newer installation of the Go language (>=Go 1.14), but may be conceptually easier to understand + maintain than nested Git repositories if you are also storing your website content in a Git repository (as we do).

First, at the command line, go to the top level of your project. Initialize your site as a hugo module. To do that, type hugo mod init and then the url where the site will be deployed (without a trailing slash at the end). For example:

hugo mod init yourname.github.io/sitename

for GitHub Pages user yourname deploying sitename.

In config.toml, add a section importing the theme as a go module:

[module]
[[module.imports]]
# theme
	path = 'git.sr.ht/~skyfaller/maxethics-hugo'

Then use the following command to install our theme as an external Hugo module:

hugo mod get -u

Your site should now be using the latest stable version of our theme. In order to update to the latest stable version of our theme, use the same command again. Then generate your site again using hugo.

To modify this theme and test it locally, add the following at the end of your go.mod file:

// To develop locally, uncomment the line below and edit it to point to your local copy
replace git.sr.ht/~skyfaller/maxethics-hugo => /home/username/maxethics-hugo

Where /home/username/maxethics-hugo is the location of your local copy of the Hugo theme. This should not be inside the "themes" folder of your website where Hugo themes were traditionally kept! Put it elsewhere on your computer.

Alternately, you can use a shell environment variable to do the local replacement, so you don't have to modify a file in this repo (and risk committing those changes). See the Hugo modules configuration documentation for details on replacements.

#Without Hugo modules (not recommended)

If for some reason you do not want to or cannot install a recent Golang, then you'll have to do without Hugo Modules, I guess. (Don't follow these directions if you are using Hugo Modules!)

If your website content is not already in a git repo, the navigate to the folder of your Hugo site and run:

  git clone https://git.sr.ht/~skyfaller/maxethics-hugo themes/maxethics-hugo

If your website content is already in a git repo, try using a git submodule instead. Inside the folder of your Hugo site run:

  git submodule add https://git.sr.ht/~skyfaller/maxethics-hugo themes/maxethics-hugo

After the theme is pulled from the git repository in some manner, edit the config.toml file of your Hugo site to include:

theme = "maxethics-hugo"

For more information read the official setup guide of Hugo.

#Transitioning away from GitHub

We are planning to Give up GitHub. As part of our migration plan, we will begin using hydra hosting, pushing to [https://brandonrozek.com/blog/git-pushing-multiple-remotes/](multiple git remotes of equal status). ([https://jigarius.com/blog/multiple-git-remote-repositories#pull-from-multiple-remotes](You can't pull from multiple remotes at once), but you can fetch.) This should make our git hosting sufficiently resilient to offset any concerns about smaller independent hosts possibly being less reliable than GitHub backed by Microsoft. Currently we're using SourceHut and Codeberg, and we intend to self-host as well.

You can run git remote set-url to switch remote locations if a host goes down. Right now, your options are:

Collaborators may prefer SSH:

git@git.sr.ht:~skyfaller/maxethics-hugo
git@codeberg.org:maximum-ethics/maxethics-hugo.git

But before pushing any commits, please make sure you know how to fetch from and push to all remotes simultaneously.

#Code of Conduct

Before contributing, please read our Code of Conduct. It's currently a verbatim copy of

#Versioning

We intend to use SemVer for versioning, but to achieve that we'll have to resist the temptation of 0-based versioning (i.e. permanent beta). For the versions available, see the tags on this repository.

#Authors

Nelson Chu Pavlosky - Initial work
Andrew Wilson - documentation

#License

This project is licensed under the GNU Affero General Public License version 3 or any later version at your choice. See the LICENSE file for details.

#Acknowledgments

We followed this excellent Creating a Hugo Theme From Scratch tutorial and borrowed from the resulting Papaya theme.
Also inspired by Hugo XMin and Black & Light
GitHub Readme Template

refs

clone