Skip to content

Wiki Style Guide

Jump to bottom
Avetis edited this page Jan 15, 2021 · 2 revisions

This page is a notice on how to edit talos wiki pages. Please read this before contributing to the talos wiki.

Questions

If you have any questions about how to edit this wiki, please do not hesitate to ask on our Discord Server

Style

We use Markdown in this wiki. To learn your way around this, here is the official Markdown Cheatsheet.

Notable syntax

  • Wiki links are made using [ [ and ] ] (without the spaces) with a | (pipe) to separate text from link. For example:

[[link text to simple page | A simple page]] renders this: link text to simple page

Do NOT use conventional []() syntax for wiki-links.

Linking to code/docs

Links are done as follows: [FileName](link to docs) [(code)](link to code) for example:

[app](https://github.com/rockbite/talos/blob/master/build.gradle)
[(code)](https://github.com/rockbite/talos/blob/master/build.gradle)

renders the following:

app (code)

Don't use non-alphabetic characters in Wiki page names, because not all operating systems can handle them when cloning Wiki as Git repository (for example, Windows doesn't support ":").

Notes on Doc Links

  • Please note that there should be a space in between FileName (Code) style formatting, in order to differentiate the two.
  • Please make the format FileName (Code) with the word Code, not Source or any derivative of that. Consistency is key!
  • If a link to documentation ends in a right paren ), it will mess up the markdown. take this as an example:
http://somewebsite.com/fancy/uri.html#sayHello()

when using the markdown formatting of []() the end paren will mess up the link, so please remember to escape the ending paren ()) so for example, it should be :

[Link to Texture#getWidth](http://somewebsite.com/fancy/uri.html#sayHello())

without the escaped paren, a 404 is imminent!

Videos

Videos are not supported on GitHub :( so we use a small workaround by posting a screenshot of the video, which leads to a link to the youtube video. Here is the syntax:

<a href="http://www.youtube.com/watch?feature=player_embedded&v=YOUTUBE_VIDEO_ID_HERE
" target="_blank"><img src="http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg"
alt="IMAGE ALT TEXT HERE" width="480" height="360" border="10" /></a>

Lets hope Github eventually supports embedded videos!

The Main Table Of Contents

If you make a page, you will most likely want it to be displayed on the main Talos wiki Table of contents and the sidebar Table of Contents. When you create an article, please create a second edit of the Home page with the appropriate positioning of your article. Mirror this change in the sidebar ToC, as to maintain likeness between the two.

Non pages on the Table of Contents

The Table of contents contains a few pages that do not have a link, and are appended with a ??. This is to signify that during translation from Google Code wiki to Github Wiki, there were a couple of pages without links. If you have something to contribute on the topic of one of those pages without a page (yet!), please feel free to add a page, and add your content, then reflect your changes in the ToC by adding a link.

Adding Images

Images are linked to with the following syntax (assuming the image is stored in the repository) ! [ ] ( https://github.com/rockbite/talos/blob/master/editor/assets/fire.png ) (without the spaces in between) which will display:

Large Multi-Page Edits

Github's web interface is the only way that a non-contributor can easily edit a wiki. If a person is to make a large edit that spans multiple pages, it can be done via the web interface, but it is recommended to take the following steps:

  • Fork the repo
  • Clone your forked repo locally
  • Make necessary changes
  • Commit and push that to your forked repo
  • Message a Talos maintainer (who has commit rights) on our to clone your repo and push it themselves.

Github does NOT have a robust pull request system for wiki changes, so this is the way it is for non-trivial changes to the wiki. If you have any problems, PLEASE contact someone from devs with your wishlist, preferably Avik (hopefully something like "please make github wikis better! $IDEAS"). If you have a problem, it is necessary that you voice yourself to Github!

Small Typo Fixes

Github wiki's diff system is not as robust as the diff system for code. If you make a tiny change, in the commit message please say "Fixed typo alpa -> alpha" or something of the sort.

Clone this wiki locally