Xfce Wiki

Sub domains
 

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
contribute:documentation:creating_new_pages [2026/09/15 23:09] – created kevinbowencontribute:documentation:creating_new_pages [2026/09/16 01:33] (current) – kevinbowen
Line 1: Line 1:
 ~~NOTOC~~ ~~NOTOC~~
-====== Formatting guidelines for new documentation/wiki pages ======+====== Formatting Guidelines for New Pages ======
  
-Most documentation contributions to docs.xfce.org and the wiki consist of small edits or modifications to specific sections of the documentation.+  * **[[#Use the NOTOC header|Use the NOTOC header]]** 
 +  * **[[#Creating a Table of Contents|Creating a Table of Contents]]** 
 +  * **[[#Using horizontal rules|Using horizontal rules]]** 
 +  * **[[#Using Back to Top links|Using Back to Top links]]** 
 +  * **[[#Creating back-links|Creating back-links]]**
  
-If a new page is needed, it is important to keep its layout and appearance consistant with the rest of the documentation. 
  
-Below are some "style" guidelines to use when creating a new documentation page.+If a new documentation, or wiki page is needed, it is important to keep its layout and appearance consistant with the rest of the documentation.
  
-1. Use the ''~~NOTOC~~'' at the very top of the page in the editing window. +Below are some guidelines to use when creating a new documentation page.
-This is a internal Dokuwiki control macro that will disable the autogeneration of a list in the sidebar. If a document becomes long enough, it is recommended to manually create and maintain a table of contents within the body of the documentation page.+
  
-As a rule of thumb, if a page becomes longer than a screen and has multiple sections, it is recommended to manually create a table of contents.+----
  
-2. Use a horizontal rule for breaking up sections of a page. +===== Use the NOTOC header =====
-A horizontal rule is creating by using ''----'' in between two black lines. Be sure to check your preview before saving to ensure that the divider properly renders.+
  
-3. If a section is long enough and the top of the page scrolls far beyond the top of the screen, insert the code ''[[|Back to Top]]'' followed by a horizontal rule to allow the reader to return back to the top of page and the table of contents.+Use the control macro ''<nowiki>~~NOTOC~~</nowiki>'' at the very top of the page in the editing window. 
 +This is a internal Dokuwiki control macro that will disable the autogeneration of a list in the sidebar. If a document becomes long enough, it is recommended to manually create and maintain a table of contents within the body of the documentation page. See also [[:wiki:syntax#sectioning|Sectioning syntax]].
  
-4.At the bottom of the page, if it makes sense, create one or two back-links to the main page. For example, on https://docs.xfce.org/xfce/thunar/thunar-archive-plugin/bugs I have included two back-links. One returns the user to the subsection on the thunar archive plugin, and the second goes back to the main thunar page.+---- 
 + 
 +===== Creating a Table of Contents ===== 
 + 
 +As a general rule, if a page becomes longer than one visual screen, and has multiple sections, it is recommended to manually create a table of contents. 
 + 
 +Using the [[:start|Main Docs.xfce.org page]] as an example, we have a table of contents consisting of three main sections 
 + 
 +<code> 
 +  * **[[#Core Modules|Core Modules]]** 
 +  * **[[#Applications|Applications]]** 
 +  * **[[#External Plugins|External Plugins]]** 
 +</code> 
 + 
 +Each link refers to a main header further down the page. 
 + 
 +---- 
 + 
 +===== Using horizontal rules ===== 
 + 
 +Use a horizontal rule for breaking up sections of a page. 
 +A horizontal rule is created by using 
 +<code> 
 +---- 
 +</code> 
 +(four dashes) in between two blank lines. Be sure to preview your changes before saving to ensure that the divider properly renders. 
 + 
 +[[|Back to Top]] 
 +---- 
 + 
 +===== Using Back to Top links ===== 
 + 
 +'Back to Top' links are used on Xfce's documentation pages as a navigational aid for readers on documentation pages that are larger than a few sentences. 
 + 
 +If a section is long enough and the top of the page scrolls far beyond the top of the screen, insert the code ''<nowiki>[[|Back to Top]]</nowiki>'' followed by a horizontal rule to allow the reader to return back to the top of page and the table of contents.  
 + 
 +<code> 
 + 
 +[[|Back to Top]] 
 +---- 
 + 
 +</code> 
 + 
 +This is not a strict rule and would depend on how large a section. If there are a number of small sections on one screen, a "Back to Top" is not neccessarily needed for each section. This is a bit of a judgement call required on the part of the editor to strike a balance between a reader's useability of the page and cluttering the page with unneeded links. 
 + 
 +---- 
 + 
 +===== Creating back-links ===== 
 + 
 +At the bottom of the page, if it makes sense, create one or two back-links to the main page. For example, on the [[:xfce:thunar:thunar-archive-plugin:bugs|Thunar-archive-plugin bugs]] page, there are two backlinks included at the bottom of the page. One returns the user to the subsection on the thunar archive plugin, and the second goes back to the main thunar page. This is coded in the editing window, as follows: 
 + 
 +<code> 
 +[[:xfce:thunar:archive|Return to thunar-archive-plugin Main Documentation Page]] 
 + 
 +[[:xfce:thunar:|Return to Thunar Main Documentation Page]] 
 +</code> 
 + 
 +Note that there is a single blank line between the two lines of code. This allows for the two links to appear separately. 
 + 
 +[[|Back to Top]] 
 +---- 
 + 
 +[[:contribute:documentation:|Return to Documentation Contribution Page]] 
 + 
 +[[:start:|Return to Main Documentation Page]]