Using the Wiki

All users may read any page on the wiki, but you may only propose changes or create new pages if you are logged in. If you want to make an edit, use the Wiki Login link in the sidebar. Choose Azure when prompted to select an authentication option.

This documentation uses Dokuwiki to provide an interface to the support materials. Dokuwiki uses a minimal markup language to edit and structure documents. If you have used any markup/markdown tools before, then you should find it pretty easy to start with; a copy of the Dokuwiki syntax guide is available here.

Once you have logged in, you can click the Edit this page link at the top of any page you wish to contribute to.

After finishing your edits to the page, save it. The newly edited page will show as a draft, and will be held in that state until it is approved by a member of the RSE team. Pages in draft state are only visible to logged-in users.

To create a new page, you must first create a link to that new page and then create the new page. The link should be created from another page which links to similar content. For example, if you are creating a new FAQ page, then you should create a link to that new page from the main FAQ index page. If you are creating a new policy page, then it should be linked to from the main Policy & Procedures index page.

In the page you want to create the link from, click the Edit this page option, and at the point you want the new link to appear, add a new link entry.

Example new page link:

[[:faq:faq_on_using_putty|How do I use Putty from Windows?]]

In the example above the :faq:faq_on_using_putty text is the destination of the link, in this case to the namespace faq, and to the page faq_on_using_putty. All links should be to an existing namespace. Do not create your own namespaces; these will be removed.

Save the edit to the existing page, and you should see the link appear - this time in red, since the page it points to does not yet exist.

Click on the red link, and the system will check that the page does not exist, and prompt you to create it. Edit the new page and save your changes.

At this point you will have made two edits; one to add the link to the original page, and one for the new page itself. Both of these edits will be held for approval by a member of the RSE team.

• The title of your page should match the link to the page you created.
• Don't edit the main wiki start page or sidebar content. Edits will not be approved to those areas.
• Don't try to create new content sections. If you think a new area should exist, then get in touch with the RSE team.
• The wiki is readable by anyone with an internet connection; it is not a suitable place to share sensitive data or research materials.

• Upload any images you use to the relevant sub-folder in media manager; if you are creating a page under FAQ, then your uploaded images should be put in the FAQ sub-folder.
• Do not remove any media files which are already present.

• Set the main page title to a level 6 header (e.g. ====== Header ======)
• Main section headers should use a level 5 header (e.g. ===== Section 1 =====)
• Main section headers will populate the left hand navigation menu
• Sub-sections at level 4 will generate collapsable elements under the left hand navigation menu

Use <code></code> blocks for showing example code of any type

For longer links to external websites and URL's, use the paragraph[(footnote)] syntax, and ensure you always have a ~~REFNOTES~~ block at the bottom of your page.

We use the Codeprism plugin, which applies programming-language-specific syntax highlighting to blocks of sample code you embed in your documentation.

Simple example:

<code lang=python el=true title=simple.py> #!/usr/bin/env python3 for i in range(1, 10): print(i) </code>

Example output:

#!/usr/bin/env python3
for i in range(1, 10):
   print(i)

This plugin adds an additional edit button to every table. Using this button the table can be edited in an Excel-like visual interface. The plugin also adds a button to the standard toolbar for inserting new tables using this editor.

No additional syntax is needed to use the plugin. Just create a table as normal and you will automatically get a small edit tag underneath, which you can use to edit the table in an Excel-like visual editor.

Mermaid is a plugin to allow the easy creation of diagrams using plain text syntax.

For example:

<mermaid>
  graph TD
    A(**mermaid**)-->B((__plugin__))
    A-->C(((//for//)))
    B-->D[["[[https://www.dokuwiki.org/dokuwiki|Dokuwiki]]"]]
    C-->D
</mermaid>

We have the Refnotes plugin installed, this allows for a nicely structured note/footnote implementation on pages where footnotes are used.

Simple example:

This is an involved sentence about some HPC job script[(For a more detailed example, see ticket #123456)].

Example output:

The text This is an involved sentence about some HPC job script would be shown in the page, and the text For a more detailed example, see ticket #123456 added as a footnote at the bottom of the page. Numbers of footnotes are automatically inserted.

We have the Wrap plugin installed, which allows additional syntax for boxes, such as the Our Wiki banner at the top of the page.

Simple example:

<WRAP box round important>
**Be Careful!**

This is a dangerous command! Be careful!
</WRAP >

Example output:

More WRAP options: