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
Nix is a powerful package manager and system configuration tool that enables reproducible, declarative, and reliable environments. Free Your Tech uses it to ensure consistent development environments across all contributors and to streamline project setup.
After cloning a project, running the nix-shell command sets up a shell environment with all the tools and dependencies needed for the project and its local development.
Setup
Running NixOS provides the best experience, though it works well on other Linux distributions, macOS, and WSL2 (Windows). We recommend the community implementation Lix, follow the instructions here to install it.
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 and LazyGit is a popular terminal UI.
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 and Pull Request Conventions
- Try to follow Conventional Commits
- 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/
# "
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 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 servein 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.