How to contribute

The Gothic Modding Community is a community-driven project. We encourage people to contribute.

This site is built with a Static Site Generator MkDocs and the Material for MkDocs theme together with multiple other MkDocs plugins.

Prerequisites for contribution differ based on the scale and type of the contribution.

Feedback

Using English, you can either open an issue via GitHub or join us on Discord.

Direct contribution

Direct contribution is made via creating a copy of this repository (a fork) and creating a pull request (PR) on GitHub with changes for approval.

Minor changes

Minor changes like fixing typos, grammatical errors or removing/adding words to paragraphs in a single file can be done quickly with the button in the upper right corner of each article. This will open up a GitHub editing interface which will create a fork with a patch branch after modifying the file and guide the user to open up the pull request.

Major changes

More elaborate changes like editing multiple files at once, adding new articles, images, other miscellaneous files or changing the configuration of the page are easier to make via external tools on your local PC. While most of these operations can be done with the GitHub interface, it is rather cumbersome, and it may be harder to spot issues during the process as changes are not immediately visible in the browser in their final form.

Some preparation is needed before working on the files as MkDocs requires an installation of Python on the system to run. GitHub works on top of git so an installation of git is also required. A basic familiarity with Terminal/Command Prompt/Powershell command line interfaces is helpful.

System setup (video)

Firstly, you should install Python. You can follow this step-by-step tutorial for Windows or macOS on how to install Python.

To work remotely with GitHub, you can install the latest version of git on your system following this tutorial.

If you just plan on editing the content of the articles with Markdown, you can simply install the latest version of Visual Studio Code for GUI git management and Markdown preview or work with any other familiar text editor and omit the environment setup.

If you are planning to do some elaborate Python programming, you can follow this step-by-step tutorial for Windows or macOS on how to set up an environment with Visual Studio Code.

System setup (text)

To prepare your system to run the project follow those instructions:

1. Install the latest version of Python .
   Make sure to select the "Add Python to PATH" option during the installation process.

2. Open up a Terminal/Command Prompt (cmd)/Powershell window.

3. Check that Python was properly installed with this command (might need a terminal restart):

   1	python --version

4. Install the latest version of git following this tutorial.

5. Check that git was properly installed with this command (might need a terminal restart):

   1	git --version

6. (optional) Install the latest version of Visual Studio Code for GUI git management and Markdown preview.

Working locally

In order to work locally:

1. Create a fork on GitHub.
2. On your local PC navigate to a directory where you want to clone your forked repository and open a Terminal window inside.

3. Clone the forked repository, using this command:

   1	git clone https://github.com/user-name/forked-repository-name.git <DIR-PATH>

   Instead of https://github.com/user-name/forked-repository-name.git use your own link which can be found after clicking on the green <> Code button and selecting the HTTPS tab.

   Replace the <DIR-PATH> with a path to a directory or . if you're inside the directory you want the project files to be cloned into.

   This will automatically create a remote origin repository pointing to your own fork.

4. Add the remote upstream repository using this command:

   1	git remote add upstream https://github.com/Gothic-Modding-Community/gmc.git

5. (optional) Create a Virtual Environment and activate it.

   If you work on multiple Python projects, it might be worthwhile to create a Virtual Environment for each project to have separate library directories with installed modules/plugins.

   1	python -m venv venv

   This will create a venv directory inside the current Terminal directory. Please keep that name as it's added to the .gitignore project file.

   Depending on the system, use one of these commands to activate the virtual environment.

   Linux / macOS
   1	source venv/bin/activate

   Windows Powershell
   1	venv\Scripts\activate.ps1

   Windows Command Prompt (cmd)
   1	venv\Scripts\activate.bat

   After activation there will be a (venv) indicator near the Terminal prompt.

   Don't close the Terminal

   The virtual environment must be activated each time a new Terminal window is opened.

6. Install MkDocs with plugins using this command:

   1	pip install -r requirements.txt

   This will install all dependencies.

7. Fetch the git history from upstream using this command:

   1	git fetch upstream

8. Checkout a new local branch based on the upstream dev branch:

   1	git checkout -b name-of-branch --track upstream/dev

   An appropriate name for a branch is either a feature name or short description of what it changes - for example 3ds-articles, fix-typos-for-contribution. They do not have to be elaborate, up-to 4 words suffices.

9. Start a server with MkDocs using this command:

   1	mkdocs serve

   Visit the local site with this url http://127.0.0.1:8000/gmc/.
   Any time you make change to any file, the website will rebuild itself and your browser will auto-refresh.

   The server may be closed using the Control-C shortcut while in the terminal/console.

10. When you are satisfied with a part of work, add and commit the files using these commands:

    1 2	git add . git commit -m "add 3 articles about ZenGin"

    An appropriate commit message should be a sentence describing the changes.

11. When you are finished with the work, push the branch to origin using this command:

    1	git push origin name-of-branch

12. Create the pull request to the appropriate branch.

    After pushing your local branch to the remote origin, there will be a link available in the Terminal window. Use it to create the pull request using the pushed branch.

13. Another contribution:

    Before contributing again, always use this command:

    1	git fetch upstream

    to make sure that you have an up-to-date upstream git history. Follow then from step 8.

    1	git status

    This command allows to check, if there are any changes in the project compared to the upstream repository.

Build preferences

While working with the project, it's possible to set various environmental variables to configure it to your own preferences:

• GMC_DEV_LOCALE - is a 2-character language identifier (ex. en, pl), it sets the development language of the site. This will enforce that language to be the default and only built language. Helps to decrease build time and allows to easily change the language without modyfying the config file. Because of changes in the mkdocs-static-i18n plugin, this is the only way to temporarily change the default language
• GMC_BUILD_ALTERNATES - True or False value, activates the site build to also include alternate languages apart of the default language. Default behaviour is to omit alternates to decrease build time.
• GMC_ENABLE_ON_PUBLISH - True or False value, activates all of the final build procedures, like adding of the last modified date, minifying of the resources etc.

Environmental variables can be set temporarily for the currently open Terminal window:

1

export GMC_DEV_LOCALE=en export GMC_BUILD_ALTERNATES=False; mkdocs serve

1
2
3

$env:GMC_DEV_LOCALE="en"
$env:GMC_BUILD_ALTERNATES="False"
mkdocs serve

1
2
3

set GMC_DEV_LOCALE=en
set GMC_BUILD_ALTERNATES=False
mkdocs serve

Build performance

To speed up the build process during development make sure that only 1 language is built, and consider using the --dirtyreload option:

1

mkdocs serve --dirtyreload

This will cause only changed .md files to rebuild. However, if you make changes to a template in the overrides directory, no changes will be visible after the rebuild, because template modification requires a full rebuild.

Submit a file

If working with git or Markdown is not viable or possible for you, you can submit files in a Google Docs format on the GMC Discord server and we will format and upload it to the page.

Translations

To provide multilingual support, our site uses the MkDocs i18n plugin.

Add new language support

To support a new language it needs to be added:

1. In the mkdocs.yml configuration, in this example we're adding the xx language:

   1 2 3 4 5 6 7 8 9 10

   plugins: - i18n: # ... languages: en: name: en - English build: true xx: name: xx - Language Name build: true

2. In the overrides/main.html file to add the announcement text for untranslated content:

   1 2 3 4 5 6 7 8 9 10 11 12

   {% set announcement = { "en": "This page has not yet been translated into LANGUAGE, therefore it is displayed in English.", "xx": "yyy", } %} {% set call_to_action = { "en": "Support us and translate!", "xx": "yyy", } %}

3. Visit the official theme site. Make sure that the theme translation is complete there. If it's not, just follow their contribution guide and come back here, there is no need to wait for the changes in the theme.

Add translated pages

Each .md file in the docs directory can have a translated version.
To add a translation for a given language create a copy with an added language suffix.
For example index.md will become index.xx.md for the xx language based on the settings in the mkdocs.yml file.

Each untranslated article has the button in the upper right corner next to the title. It allows to quickly add the translation via the GitHub interface without the need for local file configuration.