This repository contains the codebase of the Terasology website hosted at https://terasology.org/. The website provides easy access to news blog posts and impressions of the game as well as module and contribution information. Terasology and related projects are developed by a group of software enthusiast volunteers under the organization name [MovingBlocks][github movingblocks].

If you want to get in contact with the Terasology community and the whole MovingBlocks team, you can easily connect with us, share your ideas, report and solve problems. We are present in nearly the complete round-up of social networks. Follow/friend us wherever you want, chat with us and tell the world.

Terasology blog posts are authored in GitHub markdown. They typically cover relatively neutral news related to releases, recent contributions or contributor programs; however, we also value your personal project-related opinions, thoughts, and insights.

⚠️ NOTE: If you write an opinionated post about your personal experiences and views on Terasology or related topics, please add a disclaimer at the top of your blog post indicating this.

All blog posts are stored in the /blog directory with a dedicated subdirectory for each of them. Every blog post directory name consists of the publish date and blog post title: <date>-<title>, e.g. 2017-07-14-gsoc-2017-an-overview Blog post directory names should not contain non-alphanumeric characters other than dashes (-)

⚠️ NOTE: The directory name is, on a technical level, not related to the date and title in the blog post metadata. However, we ask you to comply with our convention and ensure that date and title match the blog post metadata.

Blog post directories should always contain a markdown file named index.md which will hold the blog post content and metadata. Additionally, you can provide a cover image in jpg format named cover.jpg. Optionally, any images you want to include into the blog post should be in jpg format and included in the blog post directory. Images referenced with markdown syntax (![alt](./image.jpg)) are optimized at build time; files referenced from raw HTML (<img src="./image.jpg">) are copied as-is.

To allow your blog post to show up properly on the website and search results, you'll need to use the following template in your index.md:

---
posttype: blog
title: "My first Terasology blog!"
cover: "./cover.jpg"
description: "This blog is about my latest experience with Terasology"
author: "It's me, Mario!"
date: "2023-04-08"
tags: ["Announcement"]
---

Hello world, this is my newest blog post for Terasology!
I'm so excited to share this with you!

See below the two wonderful screenshots I took.
  <div class="row">
    <div class="col-md-6"> <img src="./image-1.jpg" width="40%" /> </div>
    <div class="col-md-6"> <img src="./image-2.jpg" width="40%" /> </div>
  </div>

The upper part is metadata that will processed for nicely displaying your blog post on the website. THe lower part is your blog post content. You'll also see an example of how to include multiple images side-by-side there.

⚠️ NOTE: All the metadata fields are required.

• posttype should always be blog (without quotation marks)
• title is your news in a short phrase and also the path your blog will be published under, e.g. blog/my-first-terasology-blog (if you're writing a TeraSaturday post, please prefix it with TeraSaturday #<id>: where "<id>" is the last TeraSaturday post ID + 1)
• cover should always be "./cover.jpg" and the cover a JPG image with ratio 16:9
• description is a short one or two line summary of your blog post
• author is your name / nickname / alias - we recommend using either your GitHub or Discord name
• date is the date you want your blog post to be published aka. go online (in ISO form: YYYY-MM-DD) (this feature is no longer supported, your blog post will always be visible irrespective of the date you set)
• tags should always be an array, multiple values are possible (please tag TeraSaturday posts with "TeraSaturday")

The Terasology website is built with Astro and a few React islands for the interactive parts (blog search, module search, gallery lightbox, download picker). You need Node.js 24 or newer; npm ships with it.

npm install        # install dependencies
npm run dev        # dev server with live reload on http://localhost:4321
npm run build      # static build into dist/
npm run preview    # serve the last build
npm run check      # type-check Astro/TS files
npm run lint:js    # ESLint;  lint:css = Stylelint, format = Prettier
npm run clean      # remove build output and caches

Module and "Good First Issue" data come from the GitHub GraphQL API and need a GitHub personal access token (no extra scopes) in the environment as GITHUB_TOKEN. Without it the build still completes: it warns and renders module pages from previously cached data, or empty if there is none. Fetched data is cached for 12 hours in .astro/; npm run clean forces a refetch. Contributor program topics and mentors come from public Trello boards and need no token.

🧰 Access Tokens in CI

If the token expires, you can follow the "How to fix an expired GitHub Action token" instructions with the following adjustments:

• the token required for the module data does not require additional scopes, which means you can skip step 2
• steps 4 and 5 should be performed in the repository settings for actions and in the repository settings for dependabot on the respective MODULE_FETCH_GITHUB_TOKEN secrets

To learn more about the project structure and working of the project please refer to our docs.

The Terasology website is licensed under the MIT License.