====== Using the Wiki ======

<WRAP box round tip>
**Our Wiki**

This wiki is a collaboration between Research Software Engineering and the wider Newcastle University HPC community. We encourage all contributions to improve the documentation for everyone!
</WRAP>

===== Basic Wiki Use =====

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 [[:start?do=login|Wiki Login]] link in the sidebar. Choose **Azure** when prompted to select an authentication option.

This documentation uses [[https://www.dokuwiki.org/dokuwiki|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 [[:wiki:syntax|available here]].

===== Contributing =====
==== Editing Existing Pages ====

Once you have [[:start?do=login|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.

==== Creating New Pages ====

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:

<code>
[[:faq:faq_on_using_putty|How do I use Putty from Windows?]]
</code>

In the example above the <nowiki>:faq:faq_on_using_putty</nowiki> 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.

----
===== Style Guide ======

== General Guidance ==

   * 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.

== Images & Media ==

   * 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.

== Titles ==

   * Set the main page title to a level 6 header (e.g. <nowiki>====== Header ======</nowiki>)
   * Main section headers should use a level 5 header (e.g. <nowiki>===== Section 1 =====</nowiki>)
   * 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

== Code & Examples ==

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

== Footnotes ==

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

----

===== Plugins =====
==== Codeprism Plugin ====

We use the [[https://www.dokuwiki.org/plugin:codeprism|Codeprism]] plugin, which applies programming-language-specific syntax highlighting to blocks of sample code you embed in your documentation.

Simple example:

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

Example output:

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

----

==== EditTable Plugin ====

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 Plugin ====

[[https://www.dokuwiki.org/plugin:mermaid|Mermaid]] is a plugin to allow the easy creation of diagrams using plain text syntax.

For example:

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

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

----
==== Refnotes Plugin ====

We have the [[https://www.dokuwiki.org/plugin:refnotes|Refnotes]] plugin installed, this allows for a nicely structured note/footnote implementation on pages where footnotes are used.

Simple example:

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

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.

----

==== Wrap Plugin ====

We have the [[https://www.dokuwiki.org/plugin:wrap|Wrap]] plugin installed, which allows additional syntax for boxes, such as the //Our Wiki// banner at the top of the page.

Simple example:

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

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

Example output:

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

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

More WRAP options:

<WRAP box round info>
**Information**
Rounded, full width
</WRAP>

<WRAP box tip>
**Hints and tips**
Square, full width
</WRAP>

<WRAP box half help>
**Help**
Square, half-width
</WRAP>

<WRAP box round alert quarter>
**Alert**
Quarter-width, left aligned
</WRAP>

<WRAP box round download half right>
**Download**
Half-width, right aligned
</WRAP>

<WRAP box round todo half left>
**To Do**
Half-width, left aligned
</WRAP>