Tech Tools
This document outlines the technical tools used by Free Your Tech for collaboration and service development. The information is essential for contributors working on the website, documentation, server infrastructure, and other organizational resources.
Most tools are optimally used via Command-Line Interface, so familiarity with your system’s console or terminal is recommended.
Nix & devenv
Nix is a powerful package manager and system configuration tool that enables reproducible, declarative, and reliable environments. Devenv, built on top of Nix, simplifies development environment creation. Free Your Tech uses these tools to ensure consistent development environments across all contributors and to streamline project setup.
Setup
Running NixOS provides the best experience, though it works well on other Linux distributions, macOS, and WSL2 (Windows). Follow the instructions here to install Nix and devenv. To install devenv with Flakes (required), configure Nix beforehand:
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
Usage
For a project with existing devenv configuration:
- Clone the repository
- Run
devenv upin the project directory
This will set up all required dependencies and start any services.
Resources
Git
Git is a distributed version control system used by Free Your Tech to track changes in source code and text-based content. It enables collaborative development, maintains change history, and facilitates code branching and merging.
Setup
Many systems include Git by default. If yours doesn’t, install it using your preferred package manager or with Nix. For those less comfortable with Git’s CLI, consider using one of the available free and open-source GUI clients. VSCode users may benefit from the Git Graph extension.
Usage
At minimum, you need to understand how to clone repositories, create branches, commit changes, and push commits. For external contributions, we follow a forking workflow: create a fork of the repository on Codeberg, apply and push your changes, then create a Pull Request targeting the original repository.
Regular contributors have push access to the original repositories, but the main branch is protected and requires approved pull requests.
Branches and Pull Requests should be short-lived, focused on single tasks, and easy to review.
Commit Message Conventions
- Subject line should be 50 characters or less
- Use imperative mood in the subject line (e.g., “Add” not “Added”)
- Body should explain what and why, not how
- Reference issues like so: “Resolves freeyourtech/meta#8”
Resources
Zola
Zola is a fast static site generator written in Rust that Free Your Tech uses to build our public-facing website. It transforms Markdown content into a complete HTML website with consistent design. Our website contains information about our association, along with news articles and guides.
A static site contains no user accounts, databases, APIs, or complex servers. All content is defined in source files that are converted to website files. The server simply makes these files available at the specified web address, resulting in a fast, secure site that requires minimal maintenance.
Usage
Content is organized in the content directory, with each page as a Markdown file with front matter. Sections are created using _index.md files. For local development, clone the repository and run the local server with zola serve (or devenv up) to view your changes live.
The site is automatically built and deployed using Codeberg CI after changes are merged to main, as defined in the woodpecker configuration file.
Resources
mdBook
mdBook is a command-line tool for creating modern online books from Markdown files. Free Your Tech uses mdBook to generate our documentation site, providing a clean, navigable interface for our wiki. While similar to Zola, mdBook is specifically designed for documentation.
Usage
For a project with existing mdBook configuration:
- Clone the repository
- Run
mdbook serve(ordevenv up) in the project directory
The documentation structure:
book.toml: Configuration file for mdBooksrc/: Directory containing Markdown filesSUMMARY.md: Defines the book structure- Other
.mdfiles: Content pages
To add new content, create a Markdown file in the appropriate directory and add an entry to SUMMARY.md to include it in the navigation.
The site is automatically built and deployed using Codeberg CI after changes are merged to main, as defined in the woodpecker configuration file.