-
-
Notifications
You must be signed in to change notification settings - Fork 353
Rock Wiki Guidelines
This Rock documentation is built in Markdown and taps into the power of this Gollum powered wiki.
While we like to use a few simple conventions to ensure a homogeneous style throughout the full set of documents, please note that these are guidelines -- so don't let them scare you away from adding to this wiki.
Pages are either at the root of the wiki or in a folder of the same name as the markdown file.
To make a sidebar navigation specific to a particular page it must be inside the folder (of the same name as the markdown file) and called _Sidebar.md. It should be structured like this:
[HOME](Home) > [Appendix](_pages) > [**Rock Wiki Guidelines**](Rock-Wiki-Guidelines)
* [Page Location](Rock-Wiki-Guidelines#page-location)
* [Sidebar Navigation](Rock-Wiki-Guidelines#sidebar-navigation)
* [Page Name And Title](Rock-Wiki-Guidelines#page-name-and-title)
The title of each page will be added by the site dynamically, based on the file name; therefore it should not be written in the content itself. The file name should be the document title, with spaces replaced by dashes (-). Also, do not use any special characters in the title because they are generally not allowed in file names. Page files names must also be globally unique.
Each page should begin with a brief summary explaining what audience it targets and their key takeaways. This summary will be displayed in search results, so it should make sense by itself. It should consist of one paragraph of text, without a leading title.
If the topic is not complete enough to fulfill its goals, the top of the document should specify > Draft topic on the first line.
After the summary, the actual contents of the document should all be under section headers,
and the top section headers should be in header 1 style: # This Is A Top Header.
Headers should use capital letters to begin each word (see [capitalization][capitalization]).
[capitalization]: #Capitalization
Subsections should be one level deeper than their parent section.
Do use explicitly named anchors when building links to a specific section of the document. Anchors are automatically created by Gollum for all headers. You can manually create reference anchors by changing spaces to dashes from the header section's lowercase title.
Anchors can be linked to using the following syntax:
[How To Build Awesome Documentation][link1]
[link1]: #how-to-build-awesome-documentation
If the anchor is in another document, use the file name and the anchor name like this:
[Follow this link to learn how to build awesome documentation][link1]
[link1]: name-of-the-linked-document#how-to-build-awesome-documentation
Please note that anchor names are case-sensitive.
The text within a section should be structured in short paragraphs. Don't forget to include an empty line in wiki markup between paragraphs.
Topics should use standard Markdown and should avoid inline HTML, including styles.
Do not use header styles for emphasis.
Use _surrounding underscores_ for emphasis, which will be rendered as italics.
Use **double asterisks** for strong emphasis, which will be rendered as bold.
Use
> angle bracket paragraphsto highlight a whole paragraph as in a "NOTE:" callout.
Inline code should be surrounded by `ticks`, and multi-line code samples should be in paragraphs indented with 4 spaces.
This is a code block
Try to break code lines so that the code blocks do not have horizontal scroll bars. You can use ```(triple ticks) to start and end a code block. You can also use one of the pygment lexers after the opening triple-tick block for syntax highlighting.
```csharp
using System;
public partial class Example : Object
{
protected void Page_Load( object sender, EventArgs e )
{
}
}
```or
```aspx-cs
<%@ Control Language="C#" ClassName="HelloWorld" Inherits="Rock.Web.UI.Block"%>
<h2>Hello World</h2>
```
If you need to use sequences of characters in your text that would normally be parsed as wiki markup, such as `, * or _ but that you want to appear as they are without being parsed, add a backlash (\) in front or surround those sequences with code delimiters (`). You can look at the source of this document (click the edit link in the sidebar) for many examples of this.
The list of characters that can be escaped can be found here.
In general, images should have a width of 550px (or 430px on the UI Toolkit page).
Images should NEVER be wider than 675 pixels if they are going to be embedded into a topic. Wider images are acceptable as targets of a link from a page. The link to such a wide image should itself be a 675 pixel-wide thumbnail of the image. When including a large image, do it as a 675 pixels wide image linking to the high-resolution version. Images narrower than 675 pixels should be included with their natural width and should not be enlarged.
Images should be checked into the Rock-ChMS github wiki, in a subdirectory of the Attachments directory that has the same name as the topic's markdown file. If the image exists in small and large versions, the small one should be named the same as the full resolution, but prefixed with "s_".
The typical markup to include an image is as follows:
[[Attachments/Name-Of-Topic/NameOfImage.png]]
Note: Captions are not recommended because they just don't look all that great in the other formats that are generated from this Wiki.
If the image is a link to a higher resolution, the link and image syntaxes must be combined:
[../Attachments/Topic/s_NameOfImage.png][img1]
[img1]: ../Attachments/Topic/NameOfImage.png
If you need to link an image/graphic to another page or named anchor on the page use this syntax:
[][img1]
[img1]: Home#rock-development-101---getting-started
Acceptable image formats are PNG, JPG and GIF. Images should be reasonably compressed. Avoid JPG for screenshots, and reserve it for photos.
References to other topics on this wiki can be made using:
[Text for the link](Topic-Name)
Or:
[Text for the link][ref1]
[ref1]: Topic-Name
Links to external content can be added using:
[Text for the link](http://somesite/somepage)
Or:
[Text for the link][ref1]
[ref1]: http://somesite/somepage
If you are using the reference syntax, the references may be grouped at the end of the document, separating the link itself from the reference definition.
Do use links to specific sections of a document where relevant (see the [structure section][structure]). [structure]: #Structure
In topic titles and in section headings, use title-style capitalization (as opposed to sentence style). When referring to UI elements, follow the capitalization style used in the UI elements themselves.
Tables should be built to fit into the standard width of pages on this site. The markup to create a table is a common extension for Markdown:
Header A | Header B | Header C
-------- | -------- | --------
Cell A.1 | Cell B.1 | Cell C.1
Cell A.2 | Cell B.2 | Cell C.2
Cell A.3 | Cell B.3 | Cell C.3
This markup will create the following table:
| Header A | Header B | Header C |
|---|---|---|
| Cell A.1 | Cell B.1 | Cell C.1 |
| Cell A.2 | Cell B.2 | Cell C.2 |
| Cell A.3 | Cell B.3 | Cell C.3 |
For details of table syntax see Markdown Extra Tables Reference.
You can create quick napkin style sequence diagrams using this syntax:
{{{{{{napkin
client->server: HELO
server->client: OK
}}}}}}
which would generate a diagram like this:
{{{{{{napkin client->server: HELO server->client: OK }}}}}}
Instead of napkin you can also use vs2101 style. Additional details can be extracted from looking
at the examples on the WebSequenceDiagram website.
The
The RockChMS documentation is managed as Markdown files in a Git-powered wiki hosted on Github.
At the time of this writing, much of the structure and ideas for this wiki was adopted from the Orchard Documentation project and from Gollum as well as some ideas from the Snowplow project wiki.