Contributing to Vial

Vial is a fully open source project and open to contributions. Different aspects of the project are distributed across three repos:

• vial-kb/vial-qmk: Vial keyboard firmware, fork of qmk/qmk_firmware. Note that vial-qmk tracks the mainline QMK repo. To avoid merge conflicts, changes to core QMK code are kept to a minimum.

• vial-kb/vial-gui: Vial desktop application and the web app UI, written in Python with the fbs GUI framework.

• vial-kb/vial-kb.github.io: Vial documentation (this website). Follow the section below for details.

Contributing to these docs

The git repository for these docs is located at vial-kb/vial-kb.github.io. It is built using Jekyll and based on the Just the Docs theme. To contribute, follow these guidelines for writing and testing your changes.

Authoring content

Documentation sources are written in Markdown and parsed by Kramdown. Refer to the Kramdown Syntax guide for comprehensive documentation of supported features.

YAML metadata: Each documentation .md file begins with a triple-dash --- enclosed YAML block, defining page metadata:

---
layout: default
title: Page Title
parent: Parent Page Name
nav_order: 1
---

• layout: Typically default for standard content pages or page for standalone pages.
• title: The title displayed in the sidebar navigation and at the top of the page.
• parent: The title of the parent page for hierarchical navigation.
• nav_order: The sort order for the page within its parent section.

Links: For internal links, use Jekyll’s link syntax to the target .md file. To link to a specific section, append # after the %} and followed by the section heading in lowercase, with spaces replaced by hyphens. For external links, use the complete URL, including the protocol.

Examples:

[Internal page]({% link manual/first-use.md %})
[Internal section]({% link file.md %}#section-heading)
[External link](https://docs.qmk.fm/)

Images: Images reside in the docs/img/ directory. Reference them using relative paths:

![Alt text describing the image](../img/image-name.png)

Ensure alt text is descriptive to maintain accessibility.

Compiling the documentation

This site is built using Jekyll. To preview your changes locally, you must install Jekyll and serve the site.

1. Install Jekyll: Follow Jekyll Installation.
2. Install Dependencies: Navigate to the docs directory and install the required gems:

   bundle config set --local path 'vendor/bundle'
   bundle update
   bundle install
   

3. Serve the Site: Run the following command to start a local development server:

   bundle exec jekyll serve
   

The site will be available at http://localhost:4000.

Licenses

Vial is released under a GPL-2.0 License.

This site is based on Just the docs theme running on Jekyll.

Icons used are from Carbon Design System under an Apache-2.0 License.