Page History
Editing Best Practices (to avoid release errors)
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
Always use Relative Wiki Links!
...
For example, if you wanted to link to the Configuration page:
Harcoded Link (BAD!) | https://wiki.duraspace.org/display/DSDOC18/Configuration![]() | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="de355474-6f83-4aa4-b6bc-f024896a64a2"><ac:plain-text-body><![CDATA[ | Relative Link (Good!) | | ]]></ac:plain-text-body></ac:structured-macro> |
- Insert a new "Link"
- Under the "Search" sidetab, type in "Configuration"
- Locate the appropriate "Configuration" page in the Wiki and select it (pay close attention to the Wiki space it's in..there may be several pages called "Configuration")
- Optionally, provide custom "Link Text" (at the bottom)
Another example! This time, of a link to a specific heading on a page. Suppose you wanted to link to the Batch Metadata Editing General Configuration header on the Configuration page:
Harcoded Link (BAD!) | https://wiki.duraspace.org/display/DSDOC18/Configuration#Configuration-BatchMetadataEditing![]() | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="bfa6c868-5bb3-4ce2-b4f8-f97d47920572"><ac:plain-text-body><![CDATA[ | Relative Link (Good!) | | ]]></ac:plain-text-body></ac:structured-macro> |
One final example. It's the same as the above "Batch Metadata Editing" example, but now we are changing the text in the link to say "Configuration for Batch Metadata Editing"
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="eb5c6cc1-92e3-42c9-90f8-48f7e8eab542"><ac:plain-text-body><![CDATA[ | Harcoded Link (BAD!) | [Configuration for Batch Metadata Editing|https://wiki.duraspace.org/display/DSDOC18/Configuration#Configuration-BatchMetadataEditing] | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="3429a0e0-d3b9-44aa-b30d-6586580e993b"><ac:plain-text-body><![CDATA[ | Relative Link (Good!) | | ]]></ac:plain-text-body></ac:structured-macro> |
- Insert a new "Link"
- Select the "Advanced" sidetab
- In the "Link" field, type: "Configuration#General Configuration" (Format: "Page Name#Heading")
- In the "Link Text" field, add some text for the link (e.g. "General Configuration")
Info |
---|
You can view the source of this page for examples |
...
In the Official DSpace Documentation, we try to use a standard "table of contents" on each and every page (it's even at the top of this page).Here's the Wiki code to create that standard
- Insert a new Table of Contents
...
- Macro, with the following settings
- Output Type: list
- Display Section Numbering: (checked/selected)
- List Style: none
- Minimum Heading Level: 2
...
This table of contents does a few things:
- starts the page off with an <H1> heading (all headings after that should be h2. or h3. or h4. , etc.)
- formats the TOC like an "outline" (1, 1.1, 1.2, 2, 2.1, etc.) (Display Section Numbering = checked)
- turns off any special styling (List Style = none)
- ensures the numbering begins with the first "Heading 2" (Minimum Heading Level = 2)Ensures the TOC skips over the first <H1> heading and starts at all headings below it.
For an example, just view the Wiki Markup for this page!
Note |
---|
There may be occasional exceptions to this rule. One example is the Upgrading a DSpace Installation page, which uses a bulleted-list based Table of Contents (as the outline numbers look confusing next to the DSpace version numbers). |
...
Info |
---|
Obviously, just clicking "Edit" on any wiki page (and especially looking at the "Wiki Markup") is a great resource as well! |
Avoid special characters in page titles
Many people arrive on a specific page of the documentation after a google search. That's why it's important to ensure that the relevant keywords for the page are in the URL. This also makes URLs easy to read and share. When you put special characters in the titles, keywords will NOT show in the page URLs. Therefore, avoid special characters like brackets etc.
Official resource on special characters in page titles and effect on page urls.