Wiki

[[include in-progress (not found)]]

Wiki Overview

The wiki is a collaborative document editor which is easily edited. By default any project developer can edit the project wiki. Like most modern wiki's all edits are non-destructive -- we keep a copy of every version.

The wiki page itself has an edit button at the top right, and a discussion feature at the bottom of every page. The comment system is the same as all of the other tools in the new SourceForge system.

Like most wiki's there's a history page allows you to view the most recent edits to the wiki, and revert to any previous version.

Advanced users can modify permissions at Permissions can be modified at:
http://sourceforge.net/p/PROJECTNAME/admin/wiki/permissions

Wikis by default have a left navigation/tool sidebar and a right metadata panel which shows authorship, tags, and attachments. These can be optionally removed in the wiki's configuration options under "admin".

Markdown syntax

The wiki uses the Markdown Syntax with a few notable extensions.

Artifact Links

Any page existing forge resource can be linked with surrounding square brackets ie [mypage].

Links to resources in other tools can be explicitly referenced by adding a tool identifier prefix to the link. So for instance [developerwiki:MyTechnicalPage] and [userwiki:MySimplePage] can refer to wiki pages in a developerwiki instance. You can also link to tickets with [tickets:123] assuming there's a 123 ticket in a ForgeTracker instance mounted at tickets. The same is true for forums, or any of the other tools you have installed. You can even link to tickets in a subproject with [subproject.tickets:123].

Code Highlighting

The Code highlighting used is based on CodeHilite. It follows the same syntax as regular Markdown code blocks, except that there are two ways to tell the highlighter what language to use for the code block.

SheBang (with path)

If the first line of the codeblock contains a shebang, the language is derived from that and line numbers are used.

:::text
    #!/usr/bin/python
    # Code goes here ...

Will result in:

1 2	#!/usr/bin/python # Code goes here ...

SheBang (no path) and triple Colon

If the first line contains a shebang, but the shebang line does not contain a path (a single / or even a space) or If the first line begins with three or more colons, the text following the colons identifies the language. In both cases, the first line is removed from the code block before processing.

So, for example:

:::text
    :::python
    # Code goes here ...

Will result in just:

# Code goes here ...

Macros

macros can be used to call functions in the wiki, currently we have a number of custom macros include and img:

• The include macro looks like this: [[include ref=PAGENAME ATTRIBUTE=VALUE ATTRIBUTE2=VALUE etc]] which pulls in another wiki page into a div on the current page. The attribute fields are passed on to the div, so it can be given id, class, etc definitions for layout. This is useful where you want an announcement on every wiki page, or where you want to include some consistent navigation element in on every wiki page.

• img src=IMAGENAME surrounded by double square brackets [[ ]] -- this embeds an attached image, or image by url into the page

Tables

Everywhere you can use markdown on the newforge you can use confluence-style "|" delimited tables.

Free-form HTML

The adobe wikis can also accept a restricted subset of HTML.

Attachments

Wiki pages can store attachments for files up to ~10M, including images. Attachments are added or removed on the bottom of the edit page, and will automatically show up in links on the right hand navigation bar. Images will be automatically thumbnailed.

Administrative options

In the Admin tab there are a couple of options that you can set to customize your wiki.

The first page just lets you select the "home page" for you wiki. This is the page that you'll be sent to if you link directly to the root of the wiki. You can change this page at any time, just by entering the name of the new page in the text box.

The options page in admin provides you with the ability to remove three different pieces of the wiki functionality.

• Show discussion
• Show left bar
• Show right bar

If you want to maximize the screen realestate of the wiki, or treat it more as a CMS, you may want to remove all three of these options.

REST API

All wiki pages are read/writable via the REST API, which has 3 main functions:

• View page

Adding "/rest" as the top level directory allows you to fetch the wiki pages in JSON format ie: https://sourceforge.net/adobe/cairngorm/wiki/CairngormTools/
becomes
https://sourceforge.net/rest/adobe/cairngorm/wiki/CairngormTools/

• List pages

Similarly, prefixing the wiki tool path with "/rest" lets you see a JSON list of pages in the wiki: https://sourceforge.net/rest/adobe/cairngorm/wiki/

• Update page

Updating the wiki is done by calling the view page with additional parameters, including signed API keys. I have attached a python script which demos the basic functionality by allowing a wiki page to be created out of a markdown or HTML file, but it requires that the user create a .forge-api.ini file with the parameters:

 [keys]
 api-key=XXXXXX
 secret-key=XXXXX

These keys can be generated for your account by going to the https://sourceforge.net/auth/prefs/ page. Usage is then:

 wiki-post.py --url=WIKI_REST_PATH PAGENAME FILENAME