wiki/contributing/wiki/quickstart.md

title	description	published	date	tags	editor	dateCreated
Wiki Quickstart	How to contribute to the Aux Wiki	true	2024-07-01T19:25:14.972Z	tutorial, quickstart	markdown	2024-05-06T00:01:20.106Z

Introduction

The Auxolotl wiki runs on Wiki.js, a powerful, extensible and open-source documentation software.

It's recommended that you read the official documentation for Wiki.js before you proceed, notably the Introduction to Wiki.js and Folder Structure & Tags guides. However, we'll do the best we can to link to relevant sections.

This is a work in progress. Please help improve the documentation {.is-warning}

Account

Creating an Account

To contribute to the wiki, you need a GitHub account. If you don't have one, please follow this link to create one.

Once your account is set up, click the Login button at the top right corner and link it to this wiki.

Profile Menu

Once logged in, you can modify your profile by accessing the Account > Profile menu.

There, you can also see the pages you created and modified.

Pages

Creating a New Page

When you create a new page, all you need to do is specify where it's going to live. This is called a path. You don't need to create the folders that lead to the page path, as the wiki does this automatically.

Steps

1. From the top bar, click on the New Page button
2. Choose title, language and path of the new page then press Select
3. (Optional) Add tags and a description
4. Choose Markdown¹ as editor and start writing
5. (Optional) Add assets by using the Insert Assets button on the left toolbar
6. If you need to modify the page details (path, tags, ...), click PAGE on the top bar
7. Once you're satisfied with your changes, click on CREATE

Example:

Let's consider the following wiki structure:

 (/)
  ├── contributing
  │   └── wiki-quickstart
  ├── getting-started
  └── home

We want to create two pages with the following paths:

• /contributing/wiki
• /docs/manual/unstable/install

There should be no spaces in names and no slashes '/' at the end {.is-warning}

Since the /contributing path already exists, the wiki page will just be created under it.

However, we can see that the docs > manual > unstable folder structure does not exist. Therefore, the wiki will automatically create them for us and add the install page inside.

Following the steps above, we end up with the following structure:

 (/)
  ├── contributing
  │   ├── wiki
  │   └── wiki-quickstart
  ├── docs
  │   └── manual
  │       └── unstable
  │           └── install
  ├── getting-started
  └── home

Moving/Renaming a Page

Steps

1. Navigate to the page you want to move
2. Go to Page Actions at the top right bar, or click on the Edit Page button at the bottom
3. Click on Move/Rename and choose a new path for the file
4. (Optionally) Add, remove or modify the tags and description
5. Confirm with Select

Example

In the previous example, we've created a wiki page inside the /contributing path, but since we already have wiki-quickstart there, things might get confusing and redundant.

 (/)
  ├── contributing
  │   ├── wiki
  │   └── wiki-quickstart
  ...

To make things clearer, we want to move the wiki-quickstart page under the wiki folder:

/contributing/wiki-quickstart - - -> /contributing/wiki/quickstart

Following the steps above, we get the following structure:

 (/)
  ├── contributing
  │   └── wiki
  │       └── quickstart
  ...

Note that we nested a page quickstart inside another page wiki. This is because folders are actually just normal files, but are virtually managed as folders by the wiki. Therefore, each page is technically a folder as well.

Another way to think of it is that each folder has an initial landing page associated with it.

If you wish to know more, you can read the Folder Structure and Nesting guides {.is-info}

Tags

Tags can be used to easily and effectively categorize pages, which makes searching by topic much faster.

When adding a new tag, you need to hit Enter on your keyboard for the tag to register. This means that tags can have spaces in their names. If a tag already exists, you will have the choice to select it.

More details can be found in the Tags guide {.is-info}

After clicking on the Browse by Tags button next to the search bar, you will be presented with a screen that allows you to filter pages by one or more tags.

Markdown

You should check out the Markdown guide for a comprehensive list of all the wiki markdown formatting. However, here are a few useful things to keep in mind:

Ordered Lists

When creating ordered lists, just write 1. and the number will be automatically incremented:

1. One
1. Two
1. Three

1. One
2. Two
3. Three

Blockquotes

Blockquotes can be stylized:

> Default blockquotes
> Have no color

> `{.is-info}`
{.is-info}

...

Default blockquotes Have no color

{.is-info} {.is-info}

{.is-success} {.is-success}

{.is-warning} {.is-warning}

{.is-danger} {.is-danger}

Multi-line footnotes

Each new line should be tabbed. If you also want a newline inside the footnote, you need to use <br>:

[^2]:
	First line
  Second line<br>
  Third line

You can see the result here².

Page Source

You can view any page's Markdown source code by clicking the View Source button, either from the Page Actions from the top right, or the Edit Page at the bottom.

Footnotes

---

1. Conversion between Markdown and other editors might lead to a loss in formatting. That's why it's better to stick to one format. Currently, Markdown is the best choice since it's versatile and also easy to use.
   More details can be found in the Editors guide. ↩︎

2. First line Second line
   Third line ↩︎