mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-12-18 04:04:39 -05:00
92 lines
2.9 KiB
ReStructuredText
92 lines
2.9 KiB
ReStructuredText
===================
|
||
Website style guide
|
||
===================
|
||
|
||
|
||
This page explains the standards we follow for building and maintaining
|
||
the website. Please follow these guidelines and conventions when
|
||
modifying the website. For the standards governing the documentation in
|
||
particular, please see the :doc:`documentation style guide </developer/general/documentation-style-guide>`.
|
||
|
||
Coding conventions
|
||
------------------
|
||
|
||
|
||
The following conventions apply to the website as a whole, including
|
||
everything written in HTML, CSS, YAML, and Liquid. These conventions are
|
||
intended to keep the codebase consistent when multiple collaborators are
|
||
working on it. They should be understood as a practical set of rules for
|
||
maintaining order in this specific codebase rather than as a statement
|
||
of what is objectively right or good.
|
||
|
||
General practices
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
|
||
- Use comments to indicate the purposes of different blocks of code.
|
||
This makes the file easier to understand and navigate.
|
||
|
||
- Use descriptive variable names. Never use one or two letter variable
|
||
names. Avoid obscure abbreviations and made-up words.
|
||
|
||
- In general, make it easy for others to read your code. Your future
|
||
self will thank you, and so will your collaborators!
|
||
|
||
- `Don’t Repeat Yourself (DRY)! <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`__
|
||
Instead of repeating the same block of code multiple times, abstract
|
||
it out into a separate file and ``include`` that file where you need
|
||
it.
|
||
|
||
|
||
|
||
Whitespace
|
||
^^^^^^^^^^
|
||
|
||
|
||
- Always use spaces. Never use tabs.
|
||
|
||
- Each indentation step should be exactly two (2) spaces.
|
||
|
||
- Whenever you add an opening tag, indent the following line.
|
||
(Exception: If you open and close the tag on the same line, do not
|
||
indent the following line.)
|
||
|
||
- Indent Liquid the same way as HTML.
|
||
|
||
- In general, the starting columns of every adjacent pair of lines
|
||
should be no more than two spaces apart (example below).
|
||
|
||
- No blank or empty lines. (Hint: When you feel you need one, add a
|
||
comment on that line instead.)
|
||
|
||
|
||
|
||
Indentation example
|
||
^^^^^^^^^^^^^^^^^^^
|
||
|
||
|
||
Here’s an example that follows the indentation rules:
|
||
|
||
|
||
|
||
.. code:: html
|
||
|
||
<table>
|
||
<tr>
|
||
<th title="Anchor Link"><span class="fa fa-link"></span></th>
|
||
{% for item in secs.htmlsections[0].columns %}
|
||
<th>{{ item.title }}</th>
|
||
{% endfor %}
|
||
</tr>
|
||
{% for canary in site.data.sec-canary reversed %}
|
||
<tr id="{{ canary.canary }}">
|
||
<td><a href="#{{ canary.canary }}" class="fa fa-link black-icon" title="Anchor link to Qubes Canary row: Qubes Canary #{{ canary.canary }}"></a></td>
|
||
<td>{{ canary.date }}</td>
|
||
<td><a href="https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-{{ canary.canary }}-{{ canary.date | date: '%Y' }}.txt">Qubes Canary #{{ canary.canary }}</a></td>
|
||
</tr>
|
||
{% endfor %}
|
||
</table>
|
||
|
||
|
||
|