vennobennu / c20

A living knowledge base for the Halo CE modding community

The Reclaimers Library

This repo contains the source content and build scripts for the Reclaimers Library (https://c20.reclaimers.net). It aims to document the immense tribal knowledge of the Halo modding community and covers game engine details, the Halo Editing Kit, community tools, and guides for map-making.

Contributing

The library is not directly editable by its readers. This allows the editing team to verify information before it's added. However, we want and need the community's help filling in gaps. If you want to submit information or join the editing team, see the Contributing page.

Development

The codebase is essentially a static site generator. We use Gulp as the build task runner, with various tasks to process stylesheets, render pages, bundle JS (esbuild), and copy assets. All build results go into a dist folder that is ready to serve.

Content is written in a combination of Markdoc-flavoured markdown and YAML files for structured data, which are rendered to HTML using Preact in TypeScript. Pages are also rendered in plaintext form and bundled into a client-side search index using Minisearch. We use Sass as a CSS preprocessor.

Building and testing

In order to see content as it will appear online, you can run c20 in development mode. As a pre-requisite this project requires installing at least Node.js v14+ and Git LFS.

If you have installed Git LFS after checking out the project already, you'll need to run git lfs install and git lfs pull to download the objects. If you forget to do this the build will fail because ffmpeg will be unable to read video files as videos ("Invalid data found when processing input").

Once those are installed, clone the project and run these shell commands to get the site running locally:

# install dependencies (run once)
npm ci

# start the development server
npm run dev

You can now visit http://localhost:8080/ in a browser and see the website. Edit content source files, then refresh your browser to see changes. You can run the server on a different port with C20_PORT=9001 npm run dev.

The development server renders pages on-demand, but you can also run npm run static to fully render all pages to HTML and serve them. A full static build takes longer and isn't recommended for quick content writing. You can use it as a final step to verify the build will work once changes are merged. Note: FFmpeg is an optional dependency used to generate video thumbnails during a full build. It needs to be available on your system PATH. Windows users can simply download ffmpeg.exe and place it in the project root. If you don't want to set up FFmpeg just run C20_NO_THUMBNAILS=true npm run static and thumbnails won't be used.

Releasing

The website is currently hosted as a static site in AWS S3, fronted by a CloudFront CDN distribution, managed in reclaimers-aws. To deploy a new version, simple make changes to the master branch and a build/deploy will be triggered automatically with CodeBuild.

As a backup, users with bucket permission can simply sync the dist directory to S3:

aws s3 sync --delete ./dist s3://reclaimers-wiki-files/

Because of cache TTLs, content may not appear updated immediately. An invalidation can be run in CloudFront to force updates but it will not affect clients unless they clear their browser cache. Live content can be seen by directly viewing the S3 hosting origin.

Technical goals

An explicit choice was made to avoid typical managed or self-hosted Wiki platforms for this library and instead build a static site generator with custom features for Halo. The main tenets are:

• No API or dynamic content: the site should be easy to host and test locally with any HTTP server capable of serving files, and is easily cached on a CDN. No compute needed means low hosting costs. Even the search index is client-side.
• Respect the time of the editors. Wiki features should empower them to write faster and easier. Nobody will write if it's a chore.
• Semantic HTML: Page structures are document-like and use the right elements for the job to maintain accessibility.
• Mobile-friendly: Pages should be responsive and readable on mobile.
• The website should make minimum use of client side JavaScript unless there are interactive features needed.

Non-goals are user accounts, live editing, and on-site discussion pages. We use the pull request model and Discord discussions to ensure new information is vetted.

License

C20's codebase is licensed under version 3.0 of the GNU General Public License. A copy of its text can be found in COPYING.

The content of its pages, including articles, guides, images, tag descriptions, and other rendered metadata are available under the under the CC BY-SA 3.0 license.