This topic covers how to use wikis.
What is a Wiki?
A wiki is a collection of documents that multiple users can edit. Wiki pages can be written:
- in HTML
- plain text
- wiki syntax
Use wiki to include static text and image content, or embed live data and reports in this content, such as queries, visualizations, scripts, etc.
Users with the "Editor" role or higher can use the features described on this page. For more about how administrators manage other aspects, such as copying wikis to another container, see Wiki Admin Guide
Administrators often amend a wiki web part with an expandable Table of Contents listing of Pages
in a column to the right, and a Search
box above the Table of Contents. These web parts allows users to browse the available wiki pages (using the table of contents) and search the wiki pages for text strings (using the search box).
Create or Edit a Wiki Page
To create a new wiki page, click the New
link. To edit an existing page, click the Edit
link at the top of the displayed page.
This brings you to the wiki editor, whose features will be discussed in the following sections.Name
The page Name
identifies it uniquely within the wiki. The URL address for a wiki page includes the page name. Although you can create page names with spaces, we recommend using short but descriptive page names with no spaces and no special characters.
The first page you see in a new wiki has the page name set to "default." This designates that page as the default page for the wiki. The default page is the page that appears by default in the wiki web part. Admins can change this page later on (see Customizing the Wiki Web Part
. The page Title
appears in the title bar above the wiki page.Index
. Uncheck if the content on this page should not be searchable.Parent.
The page under which your page should be categorized in the table of contents. You cannot immediately specify the order in which a new page will appear among its siblings under its new parent. After you have saved your new page, you can adjust its order among its siblings using its Manage
link (see the Manage a Wiki Page
section below for further details). If you do not specify a parent, the page will appear at the top of your wiki's table of contents.Body.
You must include at lease one character of initial text in the Body
section of your new page. The body section contains the main text of your new wiki page. For details on formatting and linking syntax, see:
Render Mode: The "Convert To..." Button.
This button, located on the upper right side of the page, allows you to change how the wiki page is rendered. Options:
- Wiki page: The default rendering option. A page rendered as a wiki page will display special wiki markup syntax as formatted text. See Wiki Syntax for the wiki syntax reference.
- HTML: A wiki page rendered as HTML will display HTML markup as formatted text. Any legal HTML syntax is permitted in the page.
- Plain text, with links: A wiki page rendered as plain text will display text exactly as it was entered for the wiki body, with the exception of links. A recognizable link (that is, one that begins with http://, https://, ftp://, or mailto://) will be rendered as an active link.
- Markdown: Markdown syntax.
Please note that your content is not always converted when you switch between rendering methods. For example, switching a wiki-rendered page to render HTML does convert your wiki syntax to the HTML it would normally generate, but the same is not true when switching from HTML back to wiki. It is usually wise to copy your content elsewhere as a backup before switching between wiki and HTML rendering modes.Files (Attachments).
You can also add and delete attachments from within the wiki editor.Add Files
. Within the wiki editor's "Files" section below the wiki "Body," click "Attach a file", then "Browse or Choose File" to locate the file you wish to attach. Within the popup, select the file and click "Open." The file will be attached when you save the page.
Note that you cannot upload a file with the same name as an existing attachment. To replace an attachment, delete the old attachment before adding a new one of the same name.Delete Files
. Within the editor's "Files" section, click the "delete" button next to any file you have already attached in order to delete it from the page.Display Files.
Whenever you add attachments to a wiki page, the names of the files are rendered at the bottom of the displayed page. You must both attach an image and use the proper syntax to make the picture itself visible. Only then will the image itself (not just its file name) appear.Manage Display of the Attached File List.
Please see Manage Wiki Attachment List
.Save & Close Button.
Saves the current content of the page, closes the editor and renders the edited page.Save Button.
Saves the content of the editor, but does not close the editor.Cancel Button.
Cancels out of the editor and does not save changes. You return to the state of the page before you entered the editor.Delete Page Button.
Delete the page you are editing. You must confirm the deletion in a pop-up window before it is finalized. If the page has any children, you can check the box "Delete an Entire Tree/Node of Wiki Pages
" to delete all the child pages simultaneously.Show/Hide Page Tree Button.
Located on the upper right of the editor, this button toggles the visibility of your wiki's table of contents (the page tree) within the editor. It does not affect the visibility of the table of contents outside of the editor. The Shown/Hidden status of the page tree is remembered between editing sessions. Hide the page tree to make the editor page render most quickly.
The "Name" of each page in the tree appears next to its "Title." This makes it easier for you to remember the "Name" of links when editing your wiki.
Click on the "+" sign next to any node in the tree to make the list of its child pages visible. Click the "-" next to any expanded node to collapse it.Use the HTML Visual Editor
and Use the HTML Source Editor
Tabs. When you have selected "HTML" using the "Render As" drop-down menu, you have the option to use either the HTML Visual Editor or the HTML Source Editor. The Visual Editor provides a WYSIWYG editor while the Source Editor lets you edit HTML source directly.
Using the HTML Visual Editor:
- Many pages contain elements that are not supported by the visual editor. You will be warned before switching that such elements would be lost if you converted.
- To insert an image, using the Visual Editor: attach the image to the document, and enter the image name in the popup dialog.
- To view the visual editor full-screen, click the screen icon in the editor tool bar.
After you have attached an image file to a page, you need to refer to it in your page's body for the image itself to appear on your page. If you do not refer to it in your page's body, only a link to the image appears at the bottom of your page.Wiki-Language
. To add images to a wiki-language page, you must first add the image as an attachment, then refer to it in the body of the wiki page using wiki syntax such as the following: [FILENAME.PNG].HTML
. To insert an image on page rendered as HTML, you cannot use the HTML Visual Editor. After attaching your image, use the Source Editor and syntax such as the following: <img src="FILENAME.PNG"/> to show the image.
Manage a Wiki Page
Click the "Manage" link to manage the properties of a wiki page. On the Manage page, you can change the wiki page name or title, specify its parent, and specify its order in relation to its siblings. Note that if you change the page name, you will break any existing links to that page.
You can also delete the wiki page from the Manage page. Note:
When you click the Delete Page
button, you are deleting the page that you are managing, not
the page that's selected in the Sibling Order box. Make sure you double-check the name of the page that you're deleting on the delete confirmation page, so that you don't accidentally delete the wrong page.
Delete an Entire Tree/Node of Wiki Pages
When you delete a wiki page that is the parent of one or more other pages, also known as a node
of wikis, you have the option of simultaneously deleting all the children (and subchildren if such exist). From the parent page, click Manage
, then Delete
. Check the box to "Delete Entire Wiki Subtree."
You can see earlier versions of your wiki page by clicking on the "History" link at the top of any wiki page. Select the number to the left of the version of the page you would like to examine.
If you wish to make this older version of the page current, select the "Make Current" button at the bottom of the page. You can also access other numbered version of the page from the links at the bottom of any older version of the page.
Note that you will not have any way to edit a page while looking at its older version. You will need to return to the page by clicking on its name in the wiki TOC in order to edit it.
Wiki pages can be copied by administrators. For more information, see Copy Wiki Pages
Print a Wiki Page
To display a print-optimized view of a wiki page, append "_print=1" to the URL. For example:https://www.labkey.org/Documentation/wiki-page.view?name=wikiUserGuide&_print=1
You can print all wiki pages in the current folder using the Print All
option on the triangle menu above the Table of Contents. Note that all pages are concatenated into one continuous document.
You can use the "Discussion >
" link at the bottom of a wiki page to start a conversation via email or a message board specific to that page. Note that this feature can be disabled at the site level by an administrator, and that when enabled, the role "Message Board Contributor" is required to participate in message board discussions.
Check for Broken Links
You can use ordinary link checking software on a LabKey Server wiki. For example, their are a variety of in-browser plugin in link checkers that work well.
Tips for efficiency in using link checking (when available):
- Set it to exclude URLs that represent the execution of common actions on wiki pages. For example, when checking LabKey.org's documentation (at https://www.labkey.org/wiki/home/Documentation/page.view?name=default), exclude:
- Reduce the search depth.
- Turn off prompts for login certifications when checking a wiki whose content is intended to be public.
Add a Link to the Source of a Wiki Page
It is sometimes useful to include a "view source" link on wiki pages used to demonstrate the use of LabKey APIs. For example, you will see a "view source" link in the upper right of this API tutorial page
If you replace the "page" portion of the URL for a wiki page with "source", the URL will lead to the HTML source of the wiki page.
It may also be useful to open a separate page for viewing the source. In these examples, replace "default" with the appropriate page name:
- Open a LabKey-bordered copy of the source:
[<a onClick="window.open('source.view?name=default')" href="#">view source<a>]
- Open a page that includes only the source, without a LabKey border:
[<a onClick="window.open('source.view?name=default&_template=none')" href="#">view source<a>]
Navigate Using the Table of Contents
Wiki pages display a Table of Contents (TOC) in the right-hand column, titled Pages
, to help you navigate through the tree of wiki documents. You can see pages that precede and follow the page you are viewing, which will appear in bold italics (for this page, Wiki User Guide
). Click on a page to open it.Expand/Collapse TOC Sections
. Wiki documents are organized into parent/child page trees. To expand section and view child pages, click on the "+" sign next to a page name. To condense a TOC section, click on the "-" sign next to it.Expand/Collapse All
. You can use the Expand All
and Collapse All
links at the end of a wiki table of contents to collapse or expand the entire table.