Skip to content

Contributing

Welcome! If you’d like to contribute, join the #wiki channel on the Discord server and ask what you can do to help or let us know what changes you want to make.

If you aren’t familiar with creating pull requests on GitHub, see this quick video tutorial.

Setup

  1. Install Python 3.9 or later
  2. Install Git
  3. Clone the repository and install requirements:
git clone https://github.com/Hypercubers/hypercubing.xyz
cd hypercubing.xyz
python3 -m pip install -r requirements.txt --user

Run python3 -m mkdocs serve and go to http://127.0.0.1:8000/ in your web browser. As you edit files, the page will automatically refresh to show your changes.

File layout

Markdown files should have lowercase names, with hyphens to separate words. Choose shorter names when possible.

.pages

Some folders have a .pages file in them, which changes the order of pages in the navigation sidebar on the left. This uses the mkdocs-awesome-pages-plugin. Most of the time, you shouldn’t have to worry about this.

Syntax

This site uses Markdown.

For linking between files within the site, use an absolute link like this with no trailing .md:

[Melinda's physical 2^4^](/puzzles/physical/2x2x2x2/index.md) was the first 4D puzzle to have a 3D physical design.

This site uses the Material for MkDocs theme; in particular, this gives us admonitions, tables, footnotes, and subscripts & superscripts. We also have MathJax, which uses $ symbols:

The $n$th Fibonacci number is given by $F_n = F_{n-1} + F_{n-2}$.

The \(n\)th Fibonacci number is given by \(F_n = F_{n-1} + F_{n-2}\).

Adding images

We are hosting images using a private Nextcloud instance hosted on DigitalOcean. Contact HactarCE on Discord to get access to add images to be hosted there. Once you have an image somewhere in the assets folder, you can embed it in a page. When including any image, be sure to include a brief text description of the image for screen readers. For example:

![Erno Rubik inspecting Melinda's 2x2x2x2](https://assets.hypercubing.xyz/img/phys/melinda_2x2x2x2_erno_inspects.jpg)

Naming images

  • Organize images into folders when possible. If you’re adding many related images, consider making a new folder for them.
  • Use underscores when naming.
  • Use only lowercase, except when the filename includes twist notation.
  • Try to stay consistent with existing filenames.

Abbreviations

Abbreviations are listed in includes/abbreviations.md. Be careful adding new ones, lest you create another Grant Standingslice incident.

Style

When naming a puzzle with a product in its name, prefer the cross symbol x over x (e.g. 3x3x3x3 vs. 3x3x3x3). By using the unicode x in the source file, the site will automatically make it searchable using x. In an environment where you cannot use unicode x, use the HTML escape ×.