Skip to content

Commit

Permalink
doc: update readme and merge in blog author guide (#209)
Browse files Browse the repository at this point in the history 
- merge former "getting started", "prerequisites", and "development" sections
- remove old "contributing section"
- merge-in blog post authoring information from former `docs/blog-documentation.md`
- remove blog post authoring except cover image generation information from former `docs/blog-documentation.md`
- rename former `docs/blog-documentation.md` to `docs/blog-cover-generation.md`
- add "communtiy" section with links to social media
- slightly adjust readme navigation line
  • Loading branch information
@jdrueckert
jdrueckert authored Jun 30, 2023
1 parent 83f5f51 commit 4e9271f
Show file tree
Hide file tree
Showing 3 changed files with 123 additions and 115 deletions.
128 changes: 91 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
<h1 align="center">Module Showcase Website</h1>

<h5 align="center">Keeping track of Terasology's modules since 2019.</h5>
<h1 align="center">Terasology Website</h1>

[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/MovingBlocks/ModuleSite)
[![status](https://img.shields.io/badge/status-pre--alpha-red.svg)](https://github.com/MovingBlocks/ModuleSite)
Expand All @@ -9,39 +7,111 @@

---

<h3 align="center"><b>
<a href="#community">Community</a> |
<a href="#authoring-blog-posts">Authoring Blog Posts</a> |
<a href="#development">Development</a> |
<a href="#license">License</a>
</b></h3>

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].

## Community

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.

&nbsp;

<p align="center">
<a href="#about">About</a>&nbsp;&nbsp;
<a href="#setup">Setup</a>&nbsp;&nbsp;
<a href="#contributing">Contributing</a>
<a title="Discord" href="https://discord.gg/terasology"><img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/discord.svg" width="50" height="50" /></a>
&nbsp;&nbsp;&nbsp;&nbsp;
<a title="Twitter" href="https://twitter.com/Terasology"><img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/twitter.svg" width="50" height="50" /></a>
&nbsp;&nbsp;&nbsp;&nbsp;
<a title="Facebook" href="https://www.facebook.com/Terasology"><img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/facebook.svg" width="50" height="50" /></a>
&nbsp;&nbsp;&nbsp;&nbsp;
<a title="Reddit" href="http://www.reddit.com/r/Terasology"><img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/reddit.svg" width="50" height="50" /></a>
&nbsp;&nbsp;&nbsp;&nbsp;
<a title="Youtube" href="https://www.youtube.com/user/blockmaniaTV"><img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/youtube.svg" width="50" height="50" /></a>
&nbsp;&nbsp;&nbsp;&nbsp;
<a title="Patreon" href="https://www.patreon.com/Terasology"><img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/patreon.svg" width="50" height="50" /></a>
&nbsp;&nbsp;&nbsp;&nbsp;
<a title="GitHub Issues" href="https://github.com/MovingBlocks/movingblocks.github.com/issues"><img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/github.svg" width="50" height="50" /></a>
&nbsp;&nbsp;&nbsp;&nbsp;
<a title="Terasology Forum" href="https://forum.terasology.org"><img src="./static/logos/gooey_gray.png" width="48px"/></a>
</p>

---

<h2 id="about">About The Project</h2>
## Authoring Blog Posts

Terasology’s basic engine can be extended by a huge amount (201 right now!) of modules. Keeping track of them is not the easiest task. This is why this gatsby framework provides an automated generator for a website, listing all of them. This showcase website will increase discoverability by allowing to filter and search for modules by keywords and categories.
Terasology blog posts are authored in [GitHub markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). 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.
<h2> Getting Started </h2>
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 (`-`)

The module website development environment can be installed on macOS, Windows, and Linux (Debian or Ubuntu recommended). You’ll need at least 1GB of available RAM.
> **⚠️ 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.

### Blog Post Template

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"]
---
## Prerequisites
Hello world, this is my newest blog post for Terasology!
I'm so excited to share this with you!
This website is built with [Gatsby](https://www.gatsbyjs.org/).
The following tools must be installed to build and serve the website locally:
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")

* [Node.js](https://nodejs.org/en/)
* [Yarn](https://yarnpkg.com/en/)

---

## Development

Make sure that you fulfill the [prerequisites](#prerequisites) for building the website locally
The Terasology website is built with [Gatsby](https://www.gatsbyjs.org/).
A respective development environment can be installed on macOS, Windows, and Linux (Debian or Ubuntu recommended).
You’ll need at least 1GB of available RAM.

Make sure that you install the following tools to be able to build and serve the website locally:
* [Node.js](https://nodejs.org/en/)
* [Yarn](https://yarnpkg.com/en/)


To install all dependencies, run

Expand Down Expand Up @@ -83,25 +153,9 @@ To clean up built assets and caches, run
yarn run clean
```

---

> To learn more about the project structure and working of the project please refer to our [docs](docs/project-structure.md).
<h2 id="contributing">Contributing</h2>

To add a new feature or fix a bug follow the steps -

- Make sure your local workspace is up-to-date with the main repository.
- Fetch the latest code `git fetch upstream`
- Checkout to your local master branch `git checkout master`
- Merge changes from `upstream/master` to sync `git merge upstream/master`
- Create a new branch to work on the new feature or bug via the updated master branch `git checkout -b "branch_name"`
- Work on feature/bug and stage all the files to commit it on that branch `git add .` > `git commit -m "Commit Message"`
- Push the branch to your fork `git push -u origin branch_name`
- Create a pull request.

---

## Contributors
## License [![](https://img.shields.io/github/license/MovingBlocks/movingblocks.github.com)](https://opensource.org/licenses/MIT)

A list of contributors can be found [here](https://github.com/MovingBlocks/ModuleSite/graphs/contributors).
The _Terasology website_ is licensed under the [MIT License](https://opensource.org/licenses/MIT).
32 changes: 32 additions & 0 deletions docs/blog-cover-generation.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
## Generating Blog Post Covers

Generating images for TeraSaturday, TeraSpotlight and custom logo on a image require some extra arguments to be added in frontmatter

For `TeraSaturday` and `TeraSpotlight` blog

```
imageTag: "TeraSaturday"
postNumber: "#15"
mainImage: "./static/images/15.jpg"
```

`imageTag` can be TeraSaturday or TeraSpotlight, any other text will be not valid. `postNumber` is TeraSaturday or TeraSpotlight post number followed by "#" and number. `mainImage` is a path of a background in which blog writter want to overlay the TeraSaturday or TeraSpotlight text

> **⚠️ NOTE:** Their should be a dummy `cover.jpg` image in blog directory so that it can be replaced during generation and also cover image path should be `cover: "./cover.jpg"`.
For custom logo on image

```
imagetag: "Other"
customLogo: "./static/logos/gsoc.png"
mainImage: "./static/images/14.jpg"
position: "end"
```

`imageTag` will be `other` for custom logo on a image, any other text will be not valid. `customLogo` is path of the logo
.`mainImage` is a path of a background in which blog writter want to overlay the logo. `position` can be start, center or end.

After all the above setup for generating images it should be followed by command
``yarn run generate-images`

> **⚠️ NOTE:** For generating images development server should be running on different terimnal
78 changes: 0 additions & 78 deletions docs/blog-documentation.md
View file

This file was deleted.

0 comments on commit 4e9271f

Please sign in to comment.