Contributing

Contributions to this wiki are welcomed and appreciated. If you are generally experienced with Markdown/MDX and GitHub, contributing is as simple as forking the wiki repository and creating a pull request.

This guide still may be helpful for experienced users, as it will give you an idea of the specific features of Gatsby this custom theme.

If unfamiliar with this process, fear not! This guide will walk you through the contribution process in a step-by-step manner. If you still have questions, feel free to join the Discord for assistance. If completely lost, you may also submit articles to Kastle#4801 via Discord.

GitHub Desktop

Though it is possible to use GitHub's web editor, it is reccomended that you download GitHub Desktop if you plan to contribute on an ongoing basis. The linked landing page should provide a suitable download for your system. If you do not yet have a GitHub account, GitHub Desktop will prompt you to create one.

Forking the Repository

1. From the File menu, select Cline Repository...
2. Select URL and enter https://github.com/mcjava-wiki/mcjava-wiki
3. Chose the desired location of the repository on your system with Local Path
4. Click Clone
5. From the Repository menu, select Push
6. Click Fork This Repository
7. Choose To contribute to the parent project and click Continue

Editing the Repository

The files of the repository may now be editted from the location at which you cloned the repository in the previous instructions. Before editting, it is recommended that you create a new branch for each major contribution if you plan to contribute frequently. To create a new branch:

1. From the Branch menu, select New Branch...
2. Enter a name for the branch that describes your intended contribution (e.g. animated-textures)
3. Click Create Branch

To switch between branches, you may use the Current Branch tab in the top right of the window. When switching branches, GitHub Desktop will pull the files for the given branch from GitHub and update your repository folder automatically.

It is reccomended, though also not required, that you utilize a text editing application with syntax checking and highlighting. Visual Studio Code and Atom are both excellent options availible on all major operating systems.

Committing Changes

Changes are not tracked by the repository until they are committed. GitHub Desktop will show you any files you have changed in the Changes tab. Once you are satisfied with your changes, you may commit them through the GitHub Desktop GUI. It is good practice to give a reasonable summary of each commit, describing what is being changed and why. This will make the process of reviewing your pull request much smoother.

If you are not satisfied with any changes to files, you may discard those changes without committing by highlighting them, right clicking, and selecting Discard Changes. This will revert the changes to the last commit.

Pushing Changes

After making committing changes, pushing your changes to GitHub is as simple as selecting Push from the Repository menu. Generally, it is a good idea to push frequently, as this will ensure your changes are also stored on GitHub.

Opening a Pull Request

Once you are completely satisfied with your article and have pushed all needed changes, you may open a pull request for review. To create a pull request:

1. From the Branch menu, select Create Pull Request
2. After your web browser opens, login to GitHub if needed, then click Create pull request
3. Use the comment box to summarize the changes made by your pull request
4. Click Create Pull Request

After opening your PR, your proposed changes will be reviewed by a wiki administrator. They will either requst any needed changes, or if no changes are needed, merge your proposed changes into the project.

Live Previewing Changes

To build the site and preview locally, you'll need NodeJS.

1git clone https://github.com/mcjava-wiki/mcjava-wiki
2cd mcjava-wiki
3npm install #--legacy-peer-deps
4npm run develop

Changes can be live previewed with the above commands. Uncomment --legacy-peer-deps if running npm 7. If you are not able to preview your changes, do not stress. A preview will be automatically generated when you open your pull request.

Considerations

This section details considerations specific to this project based on the tools that we utilize, as well as custom features that we have added.

File Organization

The pages of this wiki are stored in the path /pages/docs of the repository. In here, you will find a folder for each section of the wiki. Please keep any contributions to the correct section. If you are unsure of the section under which a contribution fits, please ask in the Discord.

If you feel it needed to add a new section for your contribution, you may do so by adding to the sections array in gatsby-config.js. This will register the new section to the navigation bar. You may then create a new directory in /pages/docs.

Page Header

All pages must have a page header for Gatsby to register them. The page header consists of the following information:

1---
2title: Contributing
3section: About
4slug: /docs/about/contributing
5order: 3
6---

• title defines the title of the page that appears in the navigation bar
• section defines the section under which the page will appear
• slug defines the URL path of the page (e.g. /docs/about/contributing will produce the URL https://wiki.mcjava.dev/docs/about/contributing)
• order defines the position of the page in its respective section of the navigation bar, with 1 being first, and higher numbers being after

Markdown Syntax

All pages are created with MDX files. MDX is a subset of Markdown. If needed, it is also acceptable to right in plain HTML, which Gatsby should parse correctly in most cases.

MDX uses markdown syntax. A complete style guide for markdown is availible here. Here is a brief visual summary:

1# Heading Level 1
2
3This heading should only be used as the title of the page
4
5## Heading Level 2
6
7This heading should be used for major sections
8
9### Heading Level 3
10
11This heading should be used for subsections. 
12Only heading levels 2 and 3 will be displayed on the right sidebar.
13Headings go all the way to level 6 by adding more hashtags.

Heading Level 1

This heading should only be used as the title of the page

Heading Level 1

This heading should be used for major sections

Heading Level 1

This heading should be used for subsections. Only heading levels 2 and 3 will be displayed on the right sidebar. Headings go all the way to level 6 by adding more hashtags.

1**Bold Text**
2
3*Italic Text*
4
5***Bold and Italic Text***

Bold Text

Italic Text

Bold and Italic Text

1> This is a block quote
2>
3> and more

This is a block quote

and more

11. First item
22. Second item
33. Third item
4    1. Indented item
5    2. Indented item
64. Fourth item 
7
8- First item
9- Second item
10- Third item
11    - Indented item
12    - Indented item
13- Fourth item

1. First item
2. Second item
3. Third item
   1. Indented item
   2. Indented item
4. Fourth item

• First item
• Second item
• Third item
  • Indented item
  • Indented item
• Fourth item

1![Tux, the Linux mascot](./img/tux.png)

Note that we specify the path for this image relative to the mdx file of the page:

[Tux, the Linux mascot]

1There will be an extra line under this
2***

There will be an extra line under this

1My favorite browser is:
2[Firefox Developer Edition](https://www.mozilla.org/en-US/firefox/developer/ "The best browser! (and this hover tip is optional)").
3
4<https://wiki.mcjava.dev/>
5
6<[email protected]>

1`Put barticks around inline code`

Put barticks around inline code

Code Blocks

Code blocks are one of the most common components of the wiki. Consequently, an effort was made to add useful features to code blocks. The example below shows how to utilize syntax highlighting and codeblock titles.

1```json title={/path/somefile.json} highlights={2,4-6}
2{
3    "hello": "world",
4    "some_nums": [
5        1,
6        2,
7        3
8    ]
9}
10```

The tripple bartick should be followed by the language in which you are writing. Most commonly, this will be json. You may then optionally add a title using the syntax title={somefile.json}. Ensure this is seperated from the langauge by a space. You may also define lines to highlight with the syntax highlights={1,2-4}. Here, commas seperate lines and ranges, and a range can be specified with a hyphen.

The code block would then render as:

1{
2    "hello": "world",
3    "some_nums": [
4        1,
5        2,
6        3
7    ]
8}

Prism Custom Language Presets

There are also prism custom language presets for molang and mcfunction:

1say Bye...
2playsound random.explode
3teleport @s ~10 ~10 ~10 true
4say OUCH!

1(v.moo > 0) ? {
2    v.x = math.sin(q.life_time * 45);
3    v.x = v.x * v.x + 17.3;
4    t.sin_x = math.sin(v.x);
5    v.x = t.sin_x * t.sin_x + v.x * v.x;
6    v.x = math.sqrt(v.x) * v.x * math.pi;
7}

These can be defined in highlights.js and should then have appropriate entries added in custom.css to define their tag color.

Key Takeaways

• Contributions are always welcome, and are critical to the success and quality of the wiki
• The general process of contributing is:
  • Forking the repository
  • Making, committing, and pushing changes
  • Opening a pull request
• Frequent contributors should install GitHub Desktop
• The wiki is powered by Gatsby, and can be previewed locally with npm, provided NodeJS is installed
• Pages on the wiki are found under the path /pages/docs of the repository
• All pages must have a proper header specifying title, section, slug, and order
• Pages are written in MDX, which uses markdown syntax
• Code blocks have special features like titles, langauage syntax highlighting, and line highlighting
  • Define the language with no spaces after the tripple bartick (e.g. json)
  • Define a code block title with the syntax title={sometitle.json}, seperated from the language by a space
  • Define line highlighting with the syntax highlights={1,3-4}, seperated from the language by a space

Page Contributors

[Kas-tle]