ASL Manual

This is the manual found at (https://allstarlink.github.io). All contributions are welcome!

Contributing to the Manual

To view and edit the manual is simple. Simply clone the ASL-Manual project, install mkdocs (see below per platform), and begin editing.

Before cloning the project, contact N8EI and provide your GitHub account ID so you can be added to the Contributors group for this repository. This makes editing the documentation much easier than trying to fork/pull from your own copy of the repository.

Installing MkDocs is required to view/test the documentation. See the setup directions below for the appropriate platform you're running. Pages are composed in the Markdown format.

Edits should be done in a git branch and push the branch back to GitHub for developers to consider inclusion. A branch is simply a named copy of the repository that contains your changes. A branch name should be a short label of what the change is for - for example "add_foopage". A branch name cannot contain whitespace. Each branch should contain a specific set of changes that are thematically related.

The general workflow, using a terminal or PowerShell session is:

git clone https://github.com/AllStarLink/ASL3-Manual
cd ASL3-Manual
git branch some_label_here
git checkout some_label_here
mkdocs serve

Now the files may be edited. If you aren't sure what editor to use then consider using VSCode. It supports very nice syntax highlighting for Markdown. It also has plugins to help with managing a Git respository if you are unfamiliar with that.

Browse http://127.0.0.1:8000 to see the existing documentation set. As you edit files in the docs/ directory, the web browser window will be updated in real time by the running mkdocs serve command. Watch that terminal window for any error and correct them before committing code to the repository.

After all the edits have been made. Commit the changes and push the branch back to GitHub:

git commit .
git push origin some_label_here

After that, go to the GitHub repository and open a Pull Request for the changes. Describe the nature of the changes. One of the core developers much approve and accept the changed.

Setup MkDocs

ASL-Manual is generated with MkDocs. While it is possible to contribute to the manual without installing MkDocs, it would be difficult. Fortunately MkDocs is available on all normal user platforms with Python pip.

Windows 10/11

• Download and install the lastest stable version of Python3 (currently Python 3.13) with the Windows installer - Downloads
• Download and install the latest version of Git with the Windows standalone installer - Downloads
• If you are not familiar with working with SSH keys, install the GitHub cli tool:

  winget install --id GitHub.cli
  

• If you don't already have a preferred text/code editor, install VSCode from the Windows Store - Store Link
• Checkout the project as described below in Contributing to the Manual
• Install mkdocs from PowerShell

  pip install -r requirements.txt

MacOS

• Install Python3 with the Mac installer as needed brew install python3
• Checkout the project as described below in Contributing to the Manual
• Create a virtual python environment and install the necessary packages

  python3 -m venv ~/.mkdocs
  . ~/.mkdocs/bin/activate
  pip install -r requirements.txt

Every new shell, enter the python venv with . ~/.mkdocs/bin/activate before beginning to use any mkdocs commands.

Debian Linux

• Install git and Python Pip

  apt install git python3-pip

• Checkout the project as described below in Contributing to the Manual
• Create a virtual python environment and install the necessary packages

  python3 -m venv ~/.mkdocs
  . ~/.mkdocs/bin/activate
  pip install -r requirements.txt

Every new shell, enter the python venv with . ~/.mkdocs/bin/activate before beginning to use any mkdocs commands.

Guides to Help Get Started

GitHub

• Creating a GitHub account
• Verify your email with GitHub
• Authenticating to GitHub with gh
• Add an SSH key to GitHub

Basics of Git

• Get started with Git
• Basic Git

Basics of Markdown

• Markdown Syntax
• Markdown Tutorial
• MKDocs Material Markdown Add-Ons

Publishing to GitHub.io

This is for repo admins only.

You need working copies of two repositories on your local system. The directory structure should look like this:

ASL3-Manual/
    mkdocs.yml
    docs/
allstarlink.github.io/

After making and verifying your updates locally you need to change directories to the allstarlink.github.io repository and call the mkdocs gh-deploy command from there:

cd ../allstarlink.github.io/
git pull origin
git reset --hard origin/main
mkdocs gh-deploy --config-file ../ASL3-Manual/mkdocs.yml --remote-branch main

Note that you need to explicitly point to the mkdocs.yml configuration file as it is no longer in the current working directory. You also need to inform the deploy script to commit to the main branch. You may override the default with the [remote_branch] configuration setting. If you forget to change directories before running the deploy script, it will commit to the master branch of your project, which you probably don't want.

The live site will be at (https://allstarlink.github.io)