This page serves as a guide for wiki-editors. It describes the content organisation, formatting guide-lines and lines out the first steps for new editors.
Contributions to document the user interface, typical tasks (guides) for users and administrators and technical details about the openiris.io platform are very welcome.
Interested wiki-editors can contact wg-documentation@openiris.io
¶ URL Paths
The first folder-level of the paths is used to do a fundamental segmentation of conent according to content type/goal:
| Path | Type | Description |
|---|---|---|
| documentation | folder | Technical documation of the platform (UI, implementation, logic, entities). |
| guide | folder | Guides describe step-by-step how to get to one target outcome |
| in-progress | folder | Visible only to wiki editors (not for un-autenticated wiki visitors). Used for work in progress |
| Welcome | page | Brief description what openiris.io is, what the wiki is about and how to use it. Links to other imporant websites. |
| Contribute | page | How to contribute/interact with the community |
| Glossary | page | Definitions used throughout these documents. |
Only use lower case letters in URL's!
(This makes internal referencing simpler)
¶ Navigation and cross-linking
When new pages are created, the wiki readers will need to find them. Bellow is a list of locations, where pages are attributed to certain topics, that should help readers to navigate the content.
- https://wiki.openiris.io/en/guide/admin
- https://wiki.openiris.io/en/guide/user
- https://wiki.openiris.io/en/documentation
- pages in
/documention/are listing relevant guides for a given entity/view - https://wiki.openiris.io/a/navigation
After creating a new page all the above locations need to be checked and completed with the links to the new page if necessairy.
¶ Writing conventions
In order to keep the contents of the wiki consistent and well readable, editors should follow the following conventions.
| Type | Description | Directive | Example(s) | Notes |
|---|---|---|---|---|
| Content | Whenever a new page is created, the user is asked which editor to use | Use markdown | Use the icon in the editor for basic syntax, or visit the more extensive markdown documentation. | |
| Content | Maximal page size criterium | The table of content has to fit on the page without scrolling (zoom 100%) | ||
| Spelling | Capitals in titles | Capitalise only the first word | My first heading | |
| Spelling | Page titles | Follow the pattern: [ entity] [action] |
1) Resource creation 2) Resource deletion |
Pages concerning the same entity of the software naturally group together in the page-tree. |
| Formatting | References in the text to UI paths and controls | Use inline code formatting.[] need to be chosen according to context() further hints for the UI control |
Resources > Timeline > [Resource] > Settings (gear icon) |
See for the syntax of inline code. |
| Formatting | Reference to the OpenIRIS software platform | Use external link | [openiris.io](https://openiris.io)will yield: openiris.io |
Writing just openiris.io works as well |
| Formatting | References to entities in the software | Use italic font Use dashes in multi-word entities |
scheduled-resource | |
| Formatting | Resizing large images | Fix the width of the image | [logo.png](/logo.png =200x) |
Add =200x after inserting image. |
| Review | Comments, TODO's in the editing process | Use warning block quotes | > {.is-warning} |
Use the icon in the editor toolbar |
| Review | Suggestions/Discussion | Use the comments feature of wiki.js | Comments are only visible to authenticated users (not for visitors) |
¶ Minimal template
Bellow is a minimal template in markdown for a typical wiki page.
Paragraph what this page is about
# Content with images
Figures (screenshots, diagrams, etc., can have a layout using tables.
|  | |
| :-: | :-: |
|this is our beautiful logo"| here we fix the with of the image adding ` =200x` after the image path above |
## subheading 3
maybe not more than **3-4 levels**?
* unordered item 1
1. numbered item 1
2. numbered item 1
* unordered item 2
Use an icon: <span class="mdi mdi-emoticon-cool-outline"></span>
 |
|
|---|---|
| this is our beautiful logo" | here we fix the with of the image adding =100x after the image path above |
Just copy-paste the above markdown into the editor to avoid starting on a blank page.
¶ Tags
TBD: work in progress (brain storming stage)
Key features:
- Booking calendar
- Issue tracker
- Billing
Transversal topics:
- Access
- Restrictions
To search by tags click on the corresponding icon next to the search bar of right here.
¶ Icons
There is a number of public icon libraries that can be used, without having to upload any files.
They can be embedded in the content using html / webfont:
<span class="mdi mdi-xml" style="font-size: 40px"></span>
¶ Advanced syntax
There are some advanced features to achieve particular renderings of additional functions.
¶ Links (new tab)
the standard syntax of markdown does not allow for functionality like open in new tab. However this can be achieved by using html (which can be seamlessly embedded in markdown.
<a href='https://beta.openiris.io' target='_blank'>link to an external page</a>
¶ Latex
Here is a formula between $$ lines:
This also work inline using $ to demarcate beginning and end of the formula.
¶ Diagrams
Bellow is a the mermaid example from the wiki.js website: