Skip to content
This repository was archived by the owner on Jul 11, 2025. It is now read-only.
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@ This repository hosts the online documentation of the [Duality game engine](http

## What to Contribute

Both new manual pages and improvements to existing ones are greatly appreciated. If you want to contribute, but are not yet sure what to do, check out our [issue tracker](https://github.com/AdamsLair/duality-docs/issues) where we organize page requests, errors, improvements and tasks. Look out especially for issues tagged with `Help Wanted` and `Good First Issue` labels, but do not shy away from others if they look like something you'd like to do - and when in doubt, just ask.
Both new manual pages and improvements to existing ones are greatly appreciated. If you want to contribute but are unsure what to do, check out our [issue tracker](https://github.com/AdamsLair/duality-docs/issues), where we organize page requests, errors, improvements, and tasks. Look out, especially for issues tagged with `Help Wanted` and `Good First Issue` labels, but do not shy away from others if they look like something you'd like to do - and when in doubt, just ask.

## How to Contribute

The project is built upon the technology provided by [Jekyll](https://jekyllrb.com) and [GitHub Pages](https://pages.github.com). In almost all cases though, it's sufficient for you to know your way around [Markdown](https://www.google.de/search?q=markdown), the markup language in which all documentation pages are written.
The project is built upon the technology provided by [Jekyll](https://jekyllrb.com) and [GitHub Pages](https://pages.github.com). In most cases, though, it's sufficient for you to know your way around [Markdown](https://www.google.de/search?q=markdown), the markup language in which all documentation pages are written.

### Two Ways to Edit Files

The easiest way to modify or add pages is by doing so online using the GitHub web interface: Just browse to the file you want to edit, click `Edit` and GitHub will automatically fork the repository and help you create a new Pull Request once you're done editing. Using `Create new file`, you can also add new pages the same way.
The easiest way to modify or add pages is by doing so online using the GitHub web interface: Just browse to the file you want to edit, click `Edit`, and GitHub will automatically fork the repository and help you create a new Pull Request once you're done editing. Using `Create new file`, you can also add new pages the same way.

While this approach is enough for most small to medium sized contributions, bigger and more complex ones involving multiple files, images and other content usually require a bit more control. In those cases, prefer working offline and committing all your changes into a new `feature/XY` branch on your own fork of the repository, for which you can submit a new Pull Request manually as soon as you're ready for review.
While this approach is enough for most small to medium-sized contributions, bigger and more complex ones involving multiple files, images, and other content usually require a bit more control. In those cases, prefer working offline and committing all your changes into a new `feature/XY` branch on your own repository fork, for which you can submit a new Pull Request manually as soon as you're ready for review.

### Improving Existing Pages

Improvements to existing pages are often the more lightweight kind that work well by editing files directly on GitHub - for those cases, every page on the published website has an `Edit Page` button, which is essentially a shortcut to browsing to the file on GitHub and clicking `Edit` there. Feel free to use this shortcut, or go the offline route with a manually created feature branch.
Improvements to existing pages are often the more lightweight kind that works well by editing files directly on GitHub - for those cases, every page on the published website has an `Edit Page` button, which is essentially a shortcut to browsing to the file on GitHub and clicking `Edit` there. Feel free to use this shortcut or go the offline route with a manually created feature branch.

### Adding New Pages

The only difference between adding new pages and improving existing ones is that you'll need to figure out where to put the new files and how to initialize them with the right contents.
The only difference between adding new pages and improving existing ones is that you'll need to figure out where to put the new files and how to initialize them with the right content.

Generally, you'll find all pages in the [`pages`](https://github.com/AdamsLair/duality-docs/tree/master/pages) subfolder. Note that all pages need to be sorted into a subfolder that corresponds to their version code, such as `v2` or `v3`. Which name you choose for the file itself doesn't matter, but make sure to choose something that properly describes its content and ends with `.md`.
Generally, all pages are in the [`pages`](https://github.com/AdamsLair/duality-docs/tree/master/pages) subfolder. Note that all pages need to be sorted into a subfolder corresponding to their version code, such as `v2` or `v3`. Which name you choose for the file itself doesn't matter, but make sure to choose something that properly describes its content and ends with `.md`.

All pages need to specify a Jekyll Front Matter and define some style specific variables that our Jekyll templates use to structure the docs website and provide the right links to navigate it properly. A typical front matter looks like this:
All pages need to specify a Jekyll Front Matter and define some style-specific variables that our Jekyll templates use to structure the docs website and provide the right links to navigate it properly. A typical front matter looks like this:

```
---
Expand All @@ -52,4 +52,4 @@ Before submitting your new page for review, make sure to check all the points li

### Creating a Local Test Setup

For very large scale changes that require previewing content on the actual generated website, rather than just any markdown capable editor of your choice, you can set up a local Jekyll installation to get a localhost preview in your browser. This is generally not required unless you're making style or generator template changes, but if you do, take a look at [this GitHub docs page](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/).
For very large-scale changes that require previewing content on the actual generated website rather than just any markdown-capable editor of your choice, you can set up a local Jekyll installation to get a localhost preview in your browser. This is generally not required unless you're making style or generator template changes, but if you do, look at [this GitHub docs page](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/).