Coding Style Guide: Wiki

Andrew Janke edited this page Jun 4, 2015 · 3 revisions

General Wiki Code Style

Keeping an open wiki that everyone can edit is important to the project, and spirit of the project. However, some constancy in markdown formatting goes a long way to make the wiki look as good as it is informative.

Following these guidelines while making the readme for your plugin/theme would be recommended as well, but is not required.


Headers

GFM Element HTML Header Tag Equivalent Use
# <h1> This will not be used, as Github wiki pages uses the filename as h1
## <h2> Main section divider (as in this page Headers, Syntax Highlighting, etc are)
### - #### <h3> - <h4> For use in subsections
##### <h5> Please try to use this just for labeling Example in fenced code blocks
###### <h6> For descriptors in example fenced code blocks

Below is an example of how to use each header (and will be the only use of ##/h2 in abnormal circumstances).


This is a main subject (h2)

This subject has several important sub-subjects (h3)

Some sub-subjects are so vast, they require their own sub-subjects (h4)

Example: (h5)
Quick explanation of example: (h6)

Tables

Tables are pretty and easy to read; please use them whenever possible for listing aliases, functions, and anything else that could possibly be made into a table.

Syntax Highlighting

We use shell to highlight code blocks. GitHub-Flavor Markdown (GFM) does support highlighting zsh defined code blocks. However, some text editors do not, so this just makes the experience more consistent across the board.

Line Wrapping

Do not hard wrap lines.

Italics

Use underscores, not askerisks, to define italics. (This makes it easier to differentiate them from bold words/characters at glance in when editing.)

Bold

Use double asterisks, not double underscores, to define bold characters or words. (This makes it easier to differentiate them from bold words/characters at glance in when editing.)

Unnumbered lists

Use hyphens - for defining unnumbered lists and sublists, as opposed to asterisks.

Images

Use Markdown formatting for images, not HTML.

Example:
![image description](url to image)

Line Endings

Please use Unix line ending codes and not Windows (Mac OS X uses Unix by default).

EOF

Please leave a blank newline at the end of the file.

Miscellaneous

Page breaks such as ---, ___, and === don't have to be used, but if so, there are no strict guidelines on using them, just don't over use them.