style: adds pre-commit checks and formats markdown files (#14)

.devcontainer/devcontainer.json

@@ -20,9 +20,10 @@
         "vscode": {
             // Add the IDs of extensions you want installed when the container is created.
             "extensions": [
-                "tamasfe.even-better-toml",
                 "dart-code.dart-code",
-                "editorconfig.editorconfig"
+                "DavidAnson.vscode-markdownlint",
+                "editorconfig.editorconfig",
+                "tamasfe.even-better-toml"
             ]
         }
     },

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,7 @@
+---
+# adds title in frontmatter so it does not fail style check
+title: 'Pull Request Template'
+---
 <!-- Please make sure you have read the contributing guidelines -->
 
 ## Description

.github/workflows/code_style.yml

@@ -0,0 +1,49 @@
+name: Code Style
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  code-style-checks:
+    name: Code Style Checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Get exact Python version
+        run: echo "python_version=$(python --version)" >> $GITHUB_ENV
+
+      - name: Cache Virtual Environment and pre-commit cache
+        uses: actions/cache@v4
+        id: cache-pre-commit
+        with:
+          path: |
+            venv
+            pre-commit-cache
+          key: v1-venv-pre-commit-${{ runner.os }}-${{ env.python_version }}-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Install pre-commit
+        if: steps.cache-pre-commit.outputs.cache-hit != 'true'
+        run: |
+          python -m venv venv
+          source venv/bin/activate
+          pip install pre-commit
+
+      - name: Run Style Check
+        run: |
+          source venv/bin/activate
+          PRE_COMMIT_HOME="$PWD/pre-commit-cache" pre-commit run --all-files --color always --verbose --hook-stage manual

.gitpod.yml

@@ -7,6 +7,7 @@ tasks:
 
 vscode:
   extensions:
-    - tamasfe.even-better-toml
     - dart-code.dart-code
+    - DavidAnson.vscode-markdownlint
     - editorconfig.editorconfig
+    - tamasfe.even-better-toml

.markdownlint.yml

@@ -0,0 +1,34 @@
+# documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# unordered list style
+MD004:
+  style: dash
+
+# maximum line length
+# disable it
+MD013: false
+
+# multiple headings with the same context
+MD024:
+  # duplication is allowed for headings with different parents
+  siblings_only: true
+
+# code block style
+MD046:
+  style: fenced
+
+# code fence style
+MD048:
+  style: backtick
+
+# emphasis style
+MD049:
+  style: asterisk
+
+# strong style
+MD050:
+  style: asterisk
+
+# table pipe style
+MD055:
+  style: leading_and_trailing

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+      - id: check-shebang-scripts-are-executable
+
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.13.0
+    hooks:
+      # manual stage for running in the ci so that it will print out the errors
+      - id: markdownlint-cli2
+        name: Run markdownlint and log errors
+        stages: [manual]
+
+      - id: markdownlint-cli2
+        name: Run markdownlint and fix errors
+        args: [--fix]

CONTRIBUTING.md

@@ -20,15 +20,15 @@ If you have a suggestion, take a look at the existing issues and if you find a s
 
 ### Getting Started
 
-If you have a bug fix, performance improvement, feature addition, documentation imrpovement, etc. that could be useful for this respository, I would be happy to have your have your contribution. First, make sure that there does not already exist a similar pending pull request. To create a pull request, please create a fork of this repo on GitHub.
+If you have a bug fix, performance improvement, feature addition, documentation improvement, etc. that could be useful for this respository, I would be happy to have your have your contribution. First, make sure that there does not already exist a similar pending pull request. To create a pull request, please create a fork of this repo on GitHub.
 
 ### Coding
 
 #### Dart
 
 It does not really matter what editor you use; however, if you want to contribute to the Dart codebase and do not want to set up Dart on your local machine, you can use a containerized development environment with all of the requirements built-in. Here are two options:
 
-1. Gitpod. This repo has a Gitpod config already setup, so all you have to do is visit: https://gitpod.io/#https://github.com/nyoungstudios/alfa. Or replace my GitHub url with your fork.
+1. Gitpod. This repo has a Gitpod config already setup, so all you have to do is visit: <https://gitpod.io/#https://github.com/nyoungstudios/alfa>. Or replace my GitHub url with your fork.
 2. VS Code's dev container. In order to use this, clone your fork to your local machine and follow this [setup guide](https://code.visualstudio.com/docs/remote/containers) before opening the folder in VS Code. In short, you will need to install Docker and the [VS Code Remote Containers extension](https://aka.ms/vscode-remote/download/containers). Finally, when opening the repo in VS Code, it will prompt you to open it in the dev container. Then, it will build the Docker image with all the dependencies needed.
 
 To build the Dart executable, just run `make` from the repository's root directory. It will build and appropriately rename the executable to what the `install.sh` script expects.
@@ -39,7 +39,27 @@ If you like to contribute a new entry with a function to install something, you
 
 ### Style
 
-This respository uses EditorConfig to define the number of spaces for indentation as well as removing excess white characters. If your editor does not come bundled with native support, you can install the appropriate EditorConfig extension. For more information, please visit their [website](https://editorconfig.org). Additionally, if you are contributing to the Dart codebase, this repo includes a VS Code `settings.json` file with the recommended Dart editor guidelines in addiiton to the Dart linting rules defined in `analysis_options.yaml`. To run the Dart linter, you can run `dart analyze` (or `make lint`). And to apply the automated linting changes, run `dart fix --apply` (or `make fix`).
+It is important to maintain consistent coding style. This repository uses GitHub Action checks to validate that all code contributions pass the style checks. Part of the style checks are validated with [pre-commit](https://pre-commit.com). You do not need to install pre-commit locally when developing as it should be easy enough to identify the style problems by using the appropriate IDE extensions. The pre-commit checks do automatically fix a handful of style related problems, so here is how to run them locally if you like.
+
+```bash
+# install pre-commit
+pip install pre-commit
+
+# run the checks
+pre-commit run --all-files
+```
+
+#### General
+
+This respository uses EditorConfig to define the number of spaces for indentation as well as removing excess white characters. If your editor does not come bundled with native support, you can install the appropriate EditorConfig extension. For more information, please visit their [website](https://editorconfig.org).
+
+#### Markdown
+
+This repository uses [markdownlint](https://github.com/DavidAnson/markdownlint) to standardize the formatting of Markdown files. If you are using VS Code, you can install the [extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) so that warning messages will appear when something does not follow the standard.
+
+#### Dart
+
+Additionally, if you are contributing to the Dart codebase, this repo includes a VS Code `settings.json` file with the recommended Dart editor guidelines in addiiton to the Dart linting rules defined in `analysis_options.yaml`. To run the Dart linter, you can run `dart analyze` (or `make lint`). And to apply the automated linting changes, run `dart fix --apply` (or `make fix`).
 
 ### Testing
 

Dockerfile

@@ -15,7 +15,7 @@ ARG MIN="no"
 
 RUN if [ "$MIN" = "no" ]; then \
         git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k && \
-        sed -i '1 e cat /tmp/templates/p10k_init.zsh && cat /tmp/templates/zshrc_disable_flag.zsh' ~/.zshrc && \
+        sed -i '1 e cat /tmp/templates/p10k_init.zsh && echo && cat /tmp/templates/zshrc_disable_flag.zsh' ~/.zshrc && \
         sed -i 's+ZSH_THEME="robbyrussell"+ZSH_THEME="powerlevel10k/powerlevel10k"+g' ~/.zshrc; \
     else \
         sed -i '1 e cat /tmp/templates/zshrc_disable_flag.zsh' ~/.zshrc; \
@@ -32,8 +32,10 @@ RUN if [ "$MIN" = "no" ]; then \
     fi && \
     echo "" >> ~/.bashrc && \
     cat /tmp/templates/gitpod_env.zsh >> ~/.bashrc && \
+    echo "" >> ~/.bashrc && \
     echo "" >> ~/.zshrc && \
     cat /tmp/templates/gitpod_env.zsh >> ~/.zshrc && \
+    echo "" >> ~/.zshrc && \
     rm -rf /tmp/templates
 
 ENV SHELL='/bin/zsh'

README.md

@@ -2,7 +2,7 @@
 
 📋 Alfa is tool to manage and share your dev environment configuration. It's modular approach allows you to easily group different configurations together. The goal was to create a way to install all of your favorite tools whether you are running on an x86 or ARM architecture computer for both on macOS and Linux operating systems.
 
-✈️ As a flight sim enthusiast, _Alfa_ is named after the first word in the NATO phonetic alphabet. While getting a new computer is always exciting, setting it up with all your tools and settings can be a little tedious. I hope this will help simplify your preflight steps so that you can focus on the flying part.
+✈️ As a flight sim enthusiast, *Alfa* is named after the first word in the NATO phonetic alphabet. While getting a new computer is always exciting, setting it up with all your tools and settings can be a little tedious. I hope this will help simplify your preflight steps so that you can focus on the flying part.
 
 ## Prerequisites
 
@@ -21,6 +21,7 @@ cd alfa
 ```
 
 This is the installer script (more on how to use it below):
+
 ```shell
 ./install.sh -h
 ```

docs/ConfigSchema.md

@@ -78,6 +78,7 @@ echo_stuff() {
 ```
 
 And we set the options as:
+
 ```toml
 options = [
     "hi",
@@ -86,7 +87,8 @@ options = [
 ```
 
 It will print this to standard out:
-```
+
+```text
 hi
 user
 ```
@@ -102,16 +104,19 @@ echo_stuff() {
 ```
 
 And we set the env as:
+
 ```toml
 env = { NAME = "joe" }
 ```
 
 It will print this to standard out:
-```
+
+```text
 joe
 ```
 
 However, if we do not set the env, it will print this to standard out:
-```
+
+```text
 user
 ```

docs/InstallListSchema.md

@@ -32,6 +32,7 @@ custom
 ```
 
 And in this case, only these items would be installed:
+
 ```txt
 name
 item1

functions/_example/README.md

@@ -9,6 +9,7 @@ This is a example function for demostration purposes.
 ## Options
 
 Accepts any number of arguments.
+
 - each argument is a printed to stdout
 
 ## Example

functions/add_ohmyzsh_plugins/README.md

@@ -9,6 +9,7 @@ Modifies your `.zshrc` file to define which Oh My Zsh plugins to load.
 ## Options
 
 Accepts any number of arguments.
+
 - each argument is the plugin name. They can either be built-in plugins or custom plugins
 
 ## Example

functions/anaconda/README.md

@@ -9,6 +9,7 @@ Installs Anaconda 3.
 ## Options
 
 Accepts 0 or 1 arguments.
+
 - argument 1 is the url to download the anaconda installer. If not specified explicitly, it will default to the latest installer for the respective operating system and architecture that it is running on
 
 ## Environment Variables

functions/apk_packages/README.md

@@ -9,6 +9,7 @@ Installs apk packages.
 ## Options
 
 Accepts any number of arguments.
+
 - all arguments are passed after the `apk add --no-interactive` command
 
 ## Example

functions/apt_get_packages/README.md

@@ -9,6 +9,7 @@ Installs apt-get packages.
 ## Options
 
 Accepts any number of arguments.
+
 - all arguments are passed after the `apt-get install -y` command
 
 ## Example

functions/atom_packages/README.md

@@ -9,6 +9,7 @@ Installs atom packages.
 ## Options
 
 Accepts any number of arguments.
+
 - each argument is an atom package to install
 
 ## Example

functions/brew_cask_packages/README.md

@@ -9,6 +9,7 @@ Installs brew cask packages.
 ## Options
 
 Accepts any number of arguments.
+
 - each argument is a brew cask package to install
 
 ## Example

functions/brew_packages/README.md

@@ -9,6 +9,7 @@ Installs brew packages.
 ## Options
 
 Accepts any number of arguments.
+
 - each argument is a brew package to install
 
 ## Example

functions/deb_package/README.md

@@ -9,6 +9,7 @@ Installs a single deb package.
 ## Options
 
 Accepts exactly 1 argument.
+
 - argument 1 is the url to download the deb file
 
 ## Example

functions/git_clone/README.md

@@ -9,6 +9,7 @@ Clones any number of git repos to a specified parent folder. Will create the fol
 ## Options
 
 Accepts any number of arguments.
+
 - argument 1 is file path to the folder
 - each argument afterwards is the git url to clone
 

functions/git_config/README.md

@@ -9,6 +9,7 @@ Sets the git user name and git user email attributes. And creates a ssh key whic
 ## Options
 
 Accepts exactly 2 arguments
+
 - argument 1 is the git user name
 - argument 2 is the git user email
 

functions/install_ohmyzsh_plugins/README.md

@@ -9,6 +9,7 @@ Downloads Oh My Zsh plugins and saves them to your Oh My Zsh custom plugins fold
 ## Options
 
 Accepts any number of arguments.
+
 - each argument is a git url to clone the Oh My Zsh plugin from
 
 ## Example

functions/node_version/README.md

@@ -9,6 +9,7 @@ Installs the latest Node version with NVM. Or can explicitly specify which Node
 ## Options
 
 Accepts 0 or 1 arguments.
+
 - If argument 1 is given, then it will explicitly install the given Node version. Otherwise, it will install the latest Node version
 
 ## Example

functions/nvm/README.md

@@ -9,6 +9,7 @@ Installs NVM (Node Version Manager).
 ## Options
 
 Accepts 0 or 1 arguments.
+
 - If argument 1 is equal to "0", then it will not modify your profile or rc file. Otherwise, it will try to guess which profile or rc file you are using
 
 ## Example