mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-12-22 22:09:35 -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>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|