This is the source for the BARGE website. It utilizes Hugo, with the PaperMod theme.

A scrape of barge.org, taken on 23-nov-2024, is in the OLD directory. This was used for the initial content.

Any changes to this repo on the main branch will be built (via with GitHub Actions) and pushed to www.barge.org.

Read some tutorial on Markdown. We're using Goldmark, a variant of GitHub-Flavored Markdown, but any tutorial will work.

Listen to Moose Turd Pie and consider the implications.

You'll need a GitHub account to get write access to the repository or make pull requests. If you aren't currently working in software, this process will seem cumbersome. If you are working in software, this process will seem cumbersome, like a familiar, comfortable straitjacket.

If you aren't working on the templating bits or the deployment bits, and you are just writing articles in Markdown, you might be able to get by with just making changes on GitHub, which will be automatically deployed. Editing Markdown is reasonably safe, and if you make a mistake, we can fix it.

If you are just adding/editing files under content/..., yeah, you probably don't need to do setup or testing.

https://gohugo.io/installation/linux/ might help. We aren't using any of the fancypants deployment features so the "extended" edition is fine.

If you're on a Mac, you can get git and hugo via homebrew.

brew install git hugo

If you're on Debian Linux, you'll need hugo. The Debian build of hugo is too old, so you'll need to get it and build it with Go. Of course this means getting Go, and the Debian build of that is too old, too.

go install gohugoio/hugo@latest   # if on debian
git submodule update --init --recursive

Note that not everyone uses Linux, so avoid filenames that differ only by case and filenames that contain scary punctuation characters like : and ?. (Tim: this means you.)

Ask Doug.

On GitHub, just above and to the right of this text area, go to the Code dropdown and pick "ssh". Run that.

To run a local server that shows edits:

hugo serve -D --disableFastRender --renderToMemory

This is now automatic.

To produce a set of files suitable for copying to a web server:

hugo

The files are in the public directory and are suitable for copying to a web server.

To copy those files to a web server:

ssh ssh.some.server.org rm -rf /path/to/destination/\*
rsync -avzr public/ ssh.some.server.org:/path/to/destination/

(OK, that command is imperfect, but you get the idea.)

Hugo is a static site generator. Its output is fully static content. We do expect links to be relative to the current site, so it does need to be in the domain it's aware of, and at the correct level of the hierarchy.

But no databases, user management, cookies. Just web pages. Like it's 1994 again. But with @#&#^*! CSS.

Hugo supports a few file formats. Let's stick to Markdown and HTML.

All files are supposed to have front matter. This is bracketed at the top with dashes, in YAML format. This works best if it includes the document title, the document date (YYYY-MM-DD format), and maybe a summary field.

If you write Markdown (some_filename.md), you will not have access to the full scope of HTML (and this is a feature). Unlike Markdown in some other contexts, you cannot include HTML in general, and Hugo will omit it ... but you can bracket a section like this:

    {{< rawhtml }}}
    this<br>
    supports<br>
    any<br>
    markup<br>
    {{< /rawhtml }}}

... but please avoid doing this, especially for complex elements. Do not use this to modify CSS.

If you write HTML (some_filename.html), you are writing only the "body" portion of the document, not the HEAD. Hugo will supply the head portion and will wrap your text in the standard page framework. This allows using more HTML features without worrying about how raw HTML will interact with Markdown. This is not recommended, but you can find some examples where we have done that. One of them is the root page, which uses HTML because of bad interactions with the slideshow gadget and HTML validation.

If all you want to do is add br tags, there is a Hugo shortcode for this. (These are particularly important for certain trip reports which don't look right without hard line breaks.)

Hugo manages CSS and the decoration on the outside of the page (navigation bar, tags cross-links, etc). Without getting into the details, try to follow what other documents in that directory are doing.

Files that are called "_index.md" mean that the page is a literal index of the other things that are in that directory. This is good for a blog or for the in-memoriam page. In general, other pages in that directory will be enumerated at the bottom of the index page.

Files that are called "index.md" do not show the pages under that subdirectory, but let you put multiple components in that directory. I believe this is a "page bundle".

Files that are not indexes are just flat files. These can't have more components.

(These files can also be _index.html and index.html and behave the same way.)

It is OK to reorganize the site, but please provide aliases so the old links continue to work.

All pages may have a "type". We have a few different types which render slightly differently (in particular, in-memoriam, the resources page, and the results pages are all different). See the Hugo documentation for layouts.

Links should be relative, not absolute. However, for paginated pages (anything .../_index.{md,html}) links must either be absolute, or made with the relref shortcode. If this doesn't happen, Hugo will make broken links. Examples of both can be found throughout the input files.

Feel free to reorganize the site. It is OK to relocate pages, but as you do, use "aliases" in the front matter. Cool links don't change. Try to salvage dead links by pointing them at the most interesting content. There are many old links to barge.org floating around on the web, and it is sad to see them 404.

We have a top-level /news directory for things that expire. This has not been well used and is still experimental. For most articles, /blog is a good fit. For events, note that the event directories will appear in the blogroll on the root page. This is based on some Hugo configuration bits. This works great for some things and is terrible for others.

Files may be in HTML or Markdown. Whenver possible, prefer Markdown.

Our theme supports raw HTML in line with Markdown via a shortcode. Use this only as an escape mechanism, or when migrating pages from HTML to Markdown format piecemeal.

HTML entities appear in a lot of our Markdown, but do not need to. Unicode characters are fine. The exception is ampersand, which is doomed to be & forever.

Markdown should be indented with a 79-character margin.

Numbered lists should be numbered to be human-readable. Bullet lists should be marked with -. Heading should be marked with # charcters, no matter how much Tim likes underlining them. Use one asterisk (earmuffs) for italics, two for bold. Underlining is right out.

All pages need frontmatter headers. This is the bit between the "---" lines. Pages will not work correctly if this is omitted.

Make sure every page has a "title" field. Additionally, most pages will need a "summary" field. When PaperMod renders a card for a link, it will use the initial text of a page without a summary, and this usually looks mediocre.

Write all frontmatter in YAML. JSON might be OK if we had to, but it hasn't come up yet. Avoid TOML entirely.

If you find yourself repeating something, or having trouble styling something in Markdown, make a "shortcode" for it. See layouts/_shortcodes. This is currently used for a few different things. Try to avoid these as they seem likely to confuse; that said, it is better to use a shortcode than raw HTML.

If you find you need a different layout for a directory, see layouts/title-gallery for an example.

Don't write a lot of custom HTML, or depend on the details of Markdown. If you can't do it with the structure of the documents, make new structure with a shortcode. If you care about the structure of HTML (rare, but it happens) make the whole page HTML.

All results are listed in tables. All tables are rank, name, amount. If there is a tie, we list the rank multiple times prefixed by "tie".

All tournament headers for events except ToGa are done with the "tournament" shortcode.

Tables are something of a black magic in Markdown, and not all Markdown processors handle them the same way. Here are the rules that I have found relevant for Hugo:

1. A table must start with a heading (it can be empty).
2. A table is divided from its body with a bunch of horizontal lines, like this: |---|---|---|. This makes Hugo see it as a table. You may specify left- or right-justification of the rows, like this: |--:|---|---| This right-justifies all data in the first column, but the other columns will be left-justified.
3. No merging rows or columns is permitted.

Some editors will see things as tables that Hugo won't. If you do this wrong, Hugo will mangle your table. The usual gotcha for me is that Hugo requires a top heading row on a table, but Emacs doesn't. Always include this row.

If you need more complicated tables, that's a use for raw HTML. This happens on schedule pages which have complicated tables.

We have a directory called static with content that Hugo essentially doesn't manage. It parses it a little for sitemaps, but mostly it copies it over.

These files lack frontmatter, and they are not subject to Hugo's templating.

This is used for a few different purposes:

• Unmanaged HTML lives in here. This includes:
  • The rulebook HTML is managed via mdbook and its own GitHub repo.
  • Migrated content that hasn't been cleaned up may be in static.
• A few unmanaged PDFs live here. These include rulebook.pdf as well as another one that is likely a duplicate and misplaced.
• A few simple client-side redirects are managed via the static directory. These include old links to /rules/.
• Some unmanaged content still lives in the static directory. This is particularly true for atlarge, which still has some old logos, etc., that should be cleaned up.

In general, content should not go into static. Hugo won't validate it, and it's hard to make it mesh with the rest of the site. It is best if we clean this up.

Improve README.md further.

The "tournament" shortcode has a lot of flexibility to allow for transition from older results. I'd like to get rid of this, although it might be useful in rebuy tournaments. (Sometimes we say "players", sometimes we say "entries", sometimes we say "entrants". Sometimes those are different things.)

The tournament shortcode allows multiple levels of h-headings, but some of the results don't use this (relevant for ToGa). Fix.