To contribute to the Quiqr documentation, please read the following. Pull requests that do not meet the criteria described below will not be merged. Before submitting a PR:
This will improve the chances of your contribution being accepted quickly.
The Handbook is not intended to be a general guide to using the Hugo static site generator. system, as noted in the "About" section:
This handbook is not an extensive guide on how to use and configure hugo websites The purpose of this document is to explain how to install, configure, and maintain Quiqr websites ...
Thus, we are unlikely to accept contributions which add information that is not particularly Quiqr-specific.
This style guide outlines the standards for contributing to the Handbook. The manual on https://book.quiqr.org/ is generated from an hugo-book site stored in the quiqr-book repository.
Although there will always be cases where command listings are appropriate, the contents of the Handbook should be written in American English.
For markdown formatting, this project uses the default Hugo markdown format. Most valid markdown is accepted by the formatter. Read more about [Hugo markdown formatting)[https://www.markdownguide.org/tools/hugo/].
Placeholders indicate where the user should substitute the appropriate
information. They should use square brackets ([ and ]) and contain only
lower-case text, with words separated by underscores. For example:
$ cat ~/Quiqr Data/config.<site_name>.json
and not:
$ cat ~/Quiqr Data/config.[site_name].json
Link text should not include sentence-level punctuation. For example:
[Visit this site](https://example.org).
and not:
[Visit this site.](https://example.org)
Links to other sections of the Handbook use the Hugo ref shortcode.
For example:
[example]({{< ref "document#anchor" >}})
and not:
[example](./example.md#heading-text)
When referring literally to a Handbook section, the section title should be placed in double-quotes. Otherwise, double-quotes are not required. For example:
For more information, please read the "[Site workspace configuration]({{< ref "../1-workspace-conf/" >}})" section.
and
Quiqr automatically creates a [Site workspace configuration]({{< ref "../1-workspace-conf/" >}}).
Auto links (links with the same title as URL) should use the following notation:
this is an autolink https://www.example.com/ and you should not do anything else.
They should not be formatted like this:
[https://www.example.com/](https://www.example.com/)
When changing a section name, or moving a section to a different part of the
Handbook, a Hugo alias
must be added to the frontmatter section in the moved document., e.g.
---
title: page with new name
aliases:
- "/docs/page-with-old-name/"
---
Proper nouns outside of code blocks should use the casing of official information sources: e.g. 'Hugo' not 'hugo', 'GDPR' not 'gdpr', 'twitter' not 'Twitter', etc. In general, abbreviations should be upper-cased: 'CPU' for central processing unit, 'SSD' for solid state drive, 'UI' for user interface, etc.
Handbook filenames and directories should use kebab
case when splitting words. For
example the filename should be post-install.md not postinstall.md.
Prefer the active imperative voice when writing documentation. Consider the following examples:
Now we need to install the Electron and and test it.
This version is conversational and friendlier, but contains unnecessary language that may not be as clear to an ESL reader.
Install the Electron, then test if it works correctly.
This version contains a clear command to act, and a follow up that shows what will be done next. It is clear both to native English speakers, ESL readers, and to translators.
Warnings should begin with **Warning**:, and should not be block-quoted with
>. For example, the Markdown should look like:
**Warning**: Selecting the wrong option will detroy your old WordPress website.
and not:
> WARNING: Selecting the wrong option will destroy your old WordPress website.
Notes should only be used sparingly, and for non-critical information. They
should begin with a phrase such as "Note that ..." or "It should be noted that
... ", and not be block-quoted with >. For example, the Markdown should look
like:
Note that you can also use Quiqr utility X for this purpose.
and not:
> You can also use Quiqr utility X for this purpose.
Block quotes (i.e. >) should only be used to quote text from an external
source.
Proposed changes should be submitted as pull requests to the Quiqr Book repository on GitHub. Please note that, unlike a wiki, submissions will be reviewed before they are merged. If any changes are required they will need to be made before the pull request is accepted. This process is in place to ensure the quality and standards of the Quiqr Book are sustained.
You can use the edit this page link at the bottom of each page to use the online GitHub editing tools to create a fork, create a modification and send a pull request.
To clone the repository locally and push changes, git is required. It can be
installed via the git package.
Building the Quiqr Book locally requires a recent version of Hugo extended.
To fork the repository a GitHub account is needed. Once you have an account, follow GitHub's guide on setting up a fork.
Clone the repository onto your computer, enter it, and create a new branch:
$ git clone https://github.com/<your_username>/quiqr-book.git
$ cd quiqr-book
$ git checkout -b <branch_name>
You can then edit the repository files as appropriate.
To serve the docs locally and view your changes, run hugo server --minify from the
root of the repository.
If hugo server runs without errors, push your changes to your forked
repository:
$ git add <edited_file(s)>
$ git commit -m "<commit_message>"
$ git push --set-upstream origin <branch_name>
The commit message should be in the form <filename>: <description_of_changes>.
Pull requests should only contain a single commit. If a change is made after the
initial commit, git add the changed files and then run git commit --amend.
The updated commit will need to be force-pushed: git push --force.
If multiple commits are made they will need to be squashed into a single commit
with git rebase -i HEAD~X, where X is the number of commits that need to be
squashed. An editor will appear to choose which commits to squash. A second
editor will appear to choose the commit message. See
git-rebase for more information.
The updated commit will need to be force-pushed: git push --force.