¶ Getting Started
- Creating an account here
- Help! Someone asked me to create a Wiki page and I have no idea how…
- How to use Wiki.js - A nice youtube introduction into what wiki.js is and some ideas on how to use it.
- Official Wiki.js documentation
¶ User Guidelines
To aid in keeping things organised, there are some guidelines that should be (attempted) to follow:
- Try to constrain a page to a one subject: Huge pages covering different subjects make it a lot harder to find information, and should be avoided. Rather, create multiple pages and link to them when they’re relevant.
- Clear, concisive titles: Try to make it clear from your title what it describes without adding unneccessary details.
- Link pages together: Information is more valuable and more useful if it can be integrated with relating subjects. Linking pages together where it makes sense will make it easier to find information, as well as make it easier to integrate information by having easy access to its context.
- Don’t repeat: If information is available somewhere else already, link to it. If something is wrong, or could be done better, consider improving it instead of creating a new page.
- Overview pages: If multiple pages are created for a particular subject, discussing different related things about it, it might be wise to create an overview page for it. This page can be used to link the different parts of the wiki together to make things easy to find and keep the pages connected in an intuitive way.
As the wiki grows, more guidelines will be added. Feel free to suggest your own at any point!
¶ Conventions & Naming Rules
To help make things easy to find and maintain, we’ll set a couple of conventions and naming rules.
¶ Path names
- Use only lowercase for the page path.
- Keep path names short and simple if possible
- If you wish to use spaces: use the dash (
-) symbol: e.g.getting-started
¶ Page Hierarchy
- When starting a page on a new topic, create an overview page for that topic in the root of this wiki.
- Say we want to add some info on EtherCAT. Add a page with path
ethercat - The page title would then be
EtherCAT
- Say we want to add some info on EtherCAT. Add a page with path
- This overview page, contains all the basic info on that topic, and links to any page going more in-depth into the topic.
- These more in-depth pages, should be made as sub-pages of this main overview page.
- Say we want to create a subpage on the EtherCAT Configurator (a piece of software related to EtherCAT), we add a page with path
ethercat/configurator
- Say we want to create a subpage on the EtherCAT Configurator (a piece of software related to EtherCAT), we add a page with path
-
We could go further and create sub-sub-pages if we have specific guides/info on this subtopic:
/topic/sub-page/sub-sub-page -
Try to keep to a maximum of 3 layers in this hierarchy. In some cases it may be that you need to go deeper, but if a topic gets too big, it might be better to split it into several topics.
-
Sometimes it might be too much to create a separate page for a subtopic. In that case it’s fine to keep the information on the main page. However, if enough information gets added, you may always choose to later put that information into its own sub-page (keep in mind guideline 1 above).
-
If a subtopic related to multiple other topics. It’s fine (even desired) to link it in both overview pages. The path that the info will be placed can be decided based on which topic it relates to the most.
Important note: If you change a page path, any other page linking to that page will also need to be edited. Links don’t automatically update across the wiki, so be mindful of that when changing a page path!
¶ Tags
- In general, a page should have at least 1 tag assigned to it.
- Tags should always be lower case, and spaces should be
-, the same as the path naming conventions. - Before creating a new tag, first see if there is a related/similar tag already created.
- Tags can be related to, for example:
- The type of information: e.g.
overview,guide,quick-reference - The topic: e.g.
git,lokomat,ethercat
- The type of information: e.g.
- Add as many tags as make sense, but don’t go too crazy with it. (~5 tags should be the maximum as a rule of thumb).
¶ Known Bugs
It is important to note that Wiki.js is still in its early stages, so you might experience some bugs. If you do, please add them below. Also see the Github issues for more info.
- When in Markdown editing mode, you are able to add Diagrams (using the draw.io api). If you then convert the page back to the visual editor, your diagram will disappear.