Preparation for translatable jekyll content

.gitlab-ci.yml

@@ -0,0 +1,6 @@
+include:
+  - project: 'QubesOS/qubes-continuous-integration'
+    file: '/gitlab-website.yml'
+
+build:doc:
+  extends: .website

CONTRIBUTING.md

@@ -1,10 +1,12 @@
-Contributing to `qubes-doc`
-===========================
+# Contributing to `qubes-doc`
 
 Thank you for your interest in contributing to `qubes-doc`, the Qubes OS
-Project's dedicated documentation repository! Please take a moment to read our
-[Documentation Guidelines] before you begin writing. These guidelines are
-important to maintaining high quality documentation, and following them will
-increase the likelihood that your contribution will be accepted.
+Project's dedicated documentation repository! Please see [how to edit the
+documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/) for
+detailed contribution instructions.
 
-[Documentation Guidelines]: https://www.qubes-os.org/doc/doc-guidelines/
+In addition, please take a moment to read our [documentation style
+guide](https://www.qubes-os.org/doc/documentation-style-guide/) before
+contributing. These guidelines are important to maintaining high standards of
+quality, and following them will increase the likelihood that your contribution
+will be accepted.

README.md

@@ -1,17 +1,11 @@
-Qubes OS Documentation
-======================
+# Qubes OS Documentation
 
 Canonical URL: https://www.qubes-os.org/doc/
 
-All [Qubes OS Project] documentation pages are stored as plain text
-files in this dedicated repository. By cloning and regularly pulling from
-this repo, users can maintain their own up-to-date offline copy of all
-Qubes documentation rather than relying solely on the Web.
-
-For more information about the documentation, including how to contribute,
-please see the [Documentation Guidelines].
-
-
-[Qubes OS Project]: https://github.com/QubesOS
-[documentation guidelines]: https://www.qubes-os.org/doc/doc-guidelines/
+All [Qubes OS Project](https://github.com/QubesOS) documentation pages are
+stored as plain text files in this dedicated repository. By cloning and
+regularly pulling from this repo, users can maintain their own up-to-date
+offline copy of all Qubes documentation rather than relying solely on the Web.
 
+To contribute, please see [how to edit the
+documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation/).

_dev/Makefile

@@ -9,7 +9,7 @@ BUILDDIR      = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from https://www.sphinx-doc.org/)
 endif
 
 # Internal variables.

developer/building/development-workflow.md

@@ -1,25 +1,23 @@
 ---
+lang: en
 layout: doc
-title: Development Workflow
 permalink: /doc/development-workflow/
 redirect_from:
 - /en/doc/development-workflow/
 - /doc/DevelopmentWorkflow/
 - /wiki/DevelopmentWorkflow/
+ref: 66
+title: Development workflow
 ---
 
-Development Workflow
-====================
-
 A workflow for developing Qubes OS+
 
 First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
 assumes you're using qubes-builder to build Qubes.
 
-Repositories and committing Code
---------------------------------
+# Repositories and committing Code
 
-Qubes is split into a bunch of git repos. This are all contained in the
+Qubes is split into a bunch of git repos. These are all contained in the
 `qubes-src` directory under qubes-builder. Subdirectories there are separate
 components, stored in separate git repositories.
 
@@ -117,7 +115,7 @@ cd ../..
 vi series.conf
 ~~~
 
-#### Building RPMS
+#### Building RPMs
 
 TODO: Is this step generic for all subsystems?
 
@@ -130,13 +128,13 @@ distinguish between different versions of the same package.
 You might want to take a moment here to review (git diff, git status), commit
 your changes locally.
 
-To actually build RPMS, in qubes-builder:
+To actually build RPMs, in qubes-builder:
 
 ~~~
 make linux-kernel
 ~~~
 
-RPMS will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
+RPMs will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
 
 ~~~
 -rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
@@ -149,25 +147,24 @@ RPMS will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
 
 ### Useful [QubesBuilder](/doc/qubes-builder/) commands
 
-1.  `make check` - will check if all the code was committed into repository and
+1. `make check` - will check if all the code was committed into repository and
 if all repository are tagged with signed tag.
-2.  `make show-vtags` - show version of each component (based on git tags) -
+2. `make show-vtags` - show version of each component (based on git tags) -
 mostly useful just before building ISO. **Note:** this will not show version
-for components containing changes since last version tag
-3.  `make push` - push change from **all** repositories to git server. You must
+for components containing changes since last version tag.
+3. `make push` - push change from **all** repositories to git server. You must
 set proper remotes (see above) for all repositories first.
-4.  `make prepare-merge` - fetch changes from remote repositories (can be
+4. `make prepare-merge` - fetch changes from remote repositories (can be
 specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally)
 verify tags and show the changes. This do not merge the changes - there are
 left for review as FETCH\_HEAD ref. You can merge them using `git merge
 FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them.
 
-Copying Code to dom0
---------------------
+## Copying Code to dom0
 
 When developing it is convenient to be able to rapidly test changes. Assuming
 you're developing Qubes on Qubes, you should be working in a special VM for
-Qubes and occasionally you will want to transfer code or rpms back to dom0 for
+Qubes and occasionally you will want to transfer code or RPMs back to dom0 for
 testing.
 
 Here are some handy scripts Marek has shared to facilitate this.
@@ -309,7 +306,6 @@ to `testbuilder` VM. Otherwise it creates remote pointing at github account of
 the same name. In any case it points at repository matching current directory
 name.
 
-
 ## Sending packages to different VM
 
 Other useful script(s) can be used to setup local package repository hosted in
@@ -325,7 +321,7 @@ current and current-testing).
 
 ### RPM packages - yum repo
 
-In source VM, grab [linux-yum] repository (below is assumed you've made it in
+In source VM, grab [linux-yum](https://github.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in
 `~/repo-yum-upload` directory) and replace `update_repo.sh` script with:
 
 ~~~
@@ -341,7 +337,7 @@ find -type f -name '*.rpm' -delete
 qrexec-client-vm $VMNAME local.UpdateYum
 ~~~
 
-In target VM, setup actual yum repository (also based on [linux-yum], this time
+In target VM, setup actual yum repository (also based on [linux-yum](https://github.com/QubesOS/qubes-linux-yum), this time
 without modifications). You will also need to setup some gpg key for signing
 packages (it is possible to force yum to install unsigned packages, but it
 isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with
@@ -389,7 +385,7 @@ Of course you will also need to setup qrexec policy in dom0
 If you want to access the repository from network, you need to setup HTTP
 server serving it, and configure the system to let other machines actually
 reach this HTTP server. You can use for example using [port
-forwarding][port-forwarding] or setting up Tor hidden service. Configuration
+forwarding](/doc/firewall/#port-forwarding-to-a-qube-from-the-outside-world) or setting up Tor hidden service. Configuration
 details of those services are outside of the scope of this page.
 
 Usage: setup `builder.conf` in source VM to use your dummy-uploader repository:
@@ -421,10 +417,10 @@ Remember to also import gpg public key using `rpm --import`.
 
 Steps are mostly the same as in the case of yum repo. The only details that differ:
 
- - use [linux-deb] instead of [linux-yum] as a base - both in source and target VM
- - use different `update_repo.sh` script in source VM (below)
- - use `local.UpdateApt` qrexec service in target VM (code below)
- - in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
+- use [linux-deb](https://github.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://github.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM
+- use different `update_repo.sh` script in source VM (below)
+- use `local.UpdateApt` qrexec service in target VM (code below)
+- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
 
 `update_repo.sh` script:
 
@@ -540,7 +536,3 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and
 ~~~
 deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main
 ~~~
-
-[port-forwarding]: /doc/firewall/#port-forwarding-to-a-qube-from-the-outside-world
-[linux-yum]: https://github.com/QubesOS/qubes-linux-yum
-[linux-deb]: https://github.com/QubesOS/qubes-linux-deb

developer/building/qubes-builder-details.md

@@ -1,45 +1,44 @@
 ---
+lang: en
 layout: doc
-title: Qubes Builder Details
 permalink: /doc/qubes-builder-details/
 redirect_from:
 - /en/doc/qubes-builder-details/
 - /doc/QubesBuilderDetails/
 - /wiki/QubesBuilderDetails/
+ref: 65
+title: Qubes builder details
 ---
 
-[QubesBuilder](/doc/qubes-builder/) "API"
-========================================
-
 Components Makefile.builder file
 --------------------------------
 
 [QubesBuilder](/doc/qubes-builder/) expects that each component have *Makefile.builder* file in its root directory. This file specifies what should be done to build the package. As name suggests, this is normal makefile, which is included by builder as its configuration. Its main purpose is to set some variables. Generally all available variables/settings are described as comments at the beginning of Makefile.\* in [QubesBuilder](/doc/qubes-builder/).
 
 Variables for Linux build:
 
--   `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build.
--   `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package.
+- `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build.
+- `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package.
 
 Most components uses *archlinux* directory for this purpose, so its good to keep this style.
 
 Variables for Windows build:
 
--   `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available:
-    -   `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
-    -   `mingw` - MinGW (Windows gcc port). Command used to build: *make all*
--   `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*).
--   `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc.
--   `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables:
-    -   `CERT_FILENAME` Path to key file (pfx format)
-    -   `CERT_PASSWORD` Key password
-    -   `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
-    -   `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
-    -   `SIGNTOOL` Path to signtool
--   `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command.
--   `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.
--   `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\<specified directory\>/\<arch directory\>/\<actual libraries\>*), so you in mingw build you need to place libraries in some additional subdirectory.
--   `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty.
+- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available:
+  - `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
+  - `mingw` - MinGW (Windows gcc port). Command used to build: *make all*
+- `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*).
+- `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc.
+- `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables:
+  - `CERT_FILENAME` Path to key file (pfx format)
+  - `CERT_PASSWORD` Key password
+  - `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
+  - `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
+  - `SIGNTOOL` Path to signtool
+- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command.
+- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.
+- `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\<specified directory\>/\<arch directory\>/\<actual libraries\>*), so you in mingw build you need to place libraries in some additional subdirectory.
+- `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty.
 
 builder.conf settings
 ---------------------
@@ -51,4 +50,4 @@ Most settings are documented in *builder.conf.default* file, which can be used a
 Notes
 -----
 
-* For a list of custom TemplateVMs available in QubesBuilder look at [Supported Versions page](https://www.qubes-os.org/doc/supported-versions/).
+- For a list of custom TemplateVMs available in QubesBuilder look at [Supported Versions page](/doc/supported-releases/).