Skip to content

feat: add markdownlint #538

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 17 commits into
base: master
Choose a base branch
from
Open

feat: add markdownlint #538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
cf4e148
feat: add markdownlint
rwaffen Aug 27, 2025
7552519
fix(markdown): clean up _docs dir
rwaffen Aug 27, 2025
39cde45
fix(markdown): clean up _includes dir
rwaffen Aug 27, 2025
a064ea8
fix(markdown): clean up _posts dir
rwaffen Aug 27, 2025
12570f8
fix(markdown): disable MD041 - first line must be top level heading
rwaffen Aug 27, 2025
4e5fc99
fix(markdown): clean up contributing dir
rwaffen Aug 27, 2025
137284f
fix(markdown): disable MD033 - allow inline html
rwaffen Aug 27, 2025
09c3ccd
fix(markdown): clean up openvox dir
rwaffen Aug 27, 2025
adc5b90
fix(markdown): clean up plugins dir
rwaffen Aug 27, 2025
02b2035
fix(markdown): clean up privacy-policy dir
rwaffen Aug 27, 2025
99feafb
fix(markdown): clean up security dir
rwaffen Aug 27, 2025
3302dc5
fix(markdown): clean up sponsoring dir
rwaffen Aug 27, 2025
a14a490
fix(markdown): clean up voxconf dir
rwaffen Aug 27, 2025
6f189c5
fix(markdown): clean up top level
rwaffen Aug 27, 2025
956920c
fix: fail on markdown violations
rwaffen Aug 27, 2025
4945205
fix: uses aliases in config instead of rules numbers
rwaffen Aug 27, 2025
921e1fd
fix: add yaml header to markdownlint config yaml
rwaffen Aug 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: DavidAnson/markdownlint-cli2-action@v20
with:
globs: '**/*.md'
- name: Install Ruby 3
uses: ruby/setup-ruby@v1
with:
Expand Down
8 changes: 8 additions & 0 deletions .markdownlint.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
default: true

line-length: false
no-inline-html: false
first-line-heading: false
no-alt-text: false
descriptive-link-text: false
22 changes: 11 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,14 @@ what this is all about.

## Building this site

* `bundle install`
* `bundle exec jekyll serve -w --config _config.yml,_config-dev.yml`
- `bundle install`
- `bundle exec jekyll serve -w --config _config.yml,_config-dev.yml`

You can also use the rake tasks defined in the `Rakefile`:

* `build`: `jekyll build`
* `validate`: uses html-proofer to check the generated site
* `clean`: removes the `./_site` directory Jekyll generated
- `build`: `jekyll build`
- `validate`: uses html-proofer to check the generated site
- `clean`: removes the `./_site` directory Jekyll generated

## Puppet Plugins

Expand Down Expand Up @@ -93,7 +93,7 @@ by running `bundle exec rake test` and `bundle exec rake build`.

Docs can have the following header:

```
```markdown
---
layout: post
title: Deprecated and Archived Modules
Expand All @@ -104,11 +104,11 @@ last_updater: bastelfreak
---
```

* `title` will be used in the URL + in the header
* `date` is assumed as the date of publishing
* `summary` is a short roundup used on the navigation page
* `github_username` the GitHub username of the original author, optional attribute
* `last_update` the GitHub username of the author from the last update, optional attribute (if it was updated is determined by Jekyll automatically)
- `title` will be used in the URL + in the header
- `date` is assumed as the date of publishing
- `summary` is a short roundup used on the navigation page
- `github_username` the GitHub username of the original author, optional attribute
- `last_update` the GitHub username of the author from the last update, optional attribute (if it was updated is determined by Jekyll automatically)

## License

Expand Down
27 changes: 10 additions & 17 deletions _docs/arch_load_balanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ summary: A complete server/agent architecture with multiple compilers and load b
This architecture is intended for large infrastructures or dynamic infrastructures
that require the redundancy of multiple compilers.


<div class="mermaid">
graph LR;
git(Git Repository)
Expand All @@ -34,9 +33,9 @@ that require the redundancy of multiple compilers.
Agent2(Agent 2)
Agent_n(Agent n)

click HDM "https://github.com/betadots/hdm" "HDM is a web interface for analyzing and managing hiera data."
click Foreman "https://www.theforeman.org" "Foreman is a complete lifecycle management tool for physical and virtual servers."
click Webhook "https://github.com/voxpupuli/puppet_webhook" "A webhook service that can trigger code deploys from source code repository updates."
click HDM "<https://github.com/betadots/hdm>" "HDM is a web interface for analyzing and managing hiera data."
click Foreman "<https://www.theforeman.org>" "Foreman is a complete lifecycle management tool for physical and virtual servers."
click Webhook "<https://github.com/voxpupuli/puppet_webhook>" "A webhook service that can trigger code deploys from source code repository updates."

git --webhook--> Webhook
Webhook --r10k code deploy--> MainPuppetServer
Expand Down Expand Up @@ -65,14 +64,12 @@ that require the redundancy of multiple compilers.

{write a guide on how to deploy, configure, and use this architecture}


Copy link
Member

@binford2k binford2k Aug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These extra spaces between headlines are incredibly helpful when reading the source doc. Please disable this check.

### Git Repository

We recommend organizing your code as a Control Repository with branches for
environments. See the [reference repository](https://github.com/puppetlabs/control-repo)
for an example.


### Foreman

[Foreman](https://www.theforeman.org) is a complete lifecycle management tool
Expand All @@ -81,7 +78,6 @@ classifier, a Hiera data source, and report monitoring. It also includes the
power to easily automate repetitive tasks, quickly deploy applications, and
proactively manage servers, on-premise or in the cloud.


### Puppet Webhook

Configure [Puppet Webhook](https://github.com/voxpupuli/puppet_webhook) to receive
Expand All @@ -91,7 +87,6 @@ using the Bolt task from the [puppet-r10k module](https://github.com/voxpupuli/p
to trigger code deployments on each compiler, or you can also install
Puppet Webhook on each.


### Code Deployment

[r10k](https://github.com/puppetlabs/r10k) is considered the default Puppet code
Expand All @@ -100,28 +95,26 @@ infrastructure and use it to deploy your control repository as needed.

If you're a Golang shop, you might consider [g10k](https://github.com/xorpaul/g10k) as well.


### Load Balancer

Puppet Agent Server connections are connections with long duration. Therfore it is highly recommended to use `least_connection` algorithm.

Any kind of load-balancer is sufficient. [HAProxy](https://www.haproxy.org/) is well supported and allows flexibility.


### Puppet Stack

We recommend managing each of these components with the supported module.

* PuppetDB
* [puppetlabs/puppetdb](https://forge.puppet.com/puppetlabs/puppetdb)
* The default PostgreSQL database is recommended.
* [puppetlabs/puppetdb](https://forge.puppet.com/puppetlabs/puppetdb)
* The default PostgreSQL database is recommended.
* Puppet Server
* [theforeman/puppet](https://forge.puppet.com/modules/theforeman/puppet)
* [theforeman/puppet](https://forge.puppet.com/modules/theforeman/puppet)
* Puppet Agents
* [puppetlabs/puppet_agent](https://forge.puppet.com/puppetlabs/puppet_agent)
* [puppetlabs/puppet_agent](https://forge.puppet.com/puppetlabs/puppet_agent)
* Puppet Metrics Dashboard
* [puppetlabs/puppet_metrics_dashboard](https://forge.puppet.com/puppetlabs/puppet_metrics_dashboard)
* [puppetlabs/puppet_metrics_dashboard](https://forge.puppet.com/puppetlabs/puppet_metrics_dashboard)
* Hiera Data Manager (HDM)
* [puppet/hdm](https://forge.puppet.com/modules/puppet/hdm)
* [puppet/hdm](https://forge.puppet.com/modules/puppet/hdm)
* HAproxy LoadBalancer
* [puppetlabs/haproxy](https://forge.puppet.com/modules/puppetlabs/haproxy)
* [puppetlabs/haproxy](https://forge.puppet.com/modules/puppetlabs/haproxy)
35 changes: 16 additions & 19 deletions _docs/arch_single_server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,15 @@ HDM --- OpenVoxServer
Puppetboard --- OpenVoxDB
OpenVoxServer --- Agent1("Agent 1") & Agent2("Agent 2") & Agent_n("Agent n")

click Foreman "https://www.theforeman.org/"
Copy link
Member

@binford2k binford2k Aug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this code is a mermaid diagram

click Webhook "https://github.com/voxpupuli/webhook-go?tab=readme-ov-file#webhook-go"
click OpenVoxDB "https://github.com/OpenVoxProject/openvoxdb"
click HDM "https://github.com/betadots/hdm?tab=readme-ov-file#hdm---hiera-data-manager"
click Puppetboard "https://github.com/voxpupuli/puppetboard?tab=readme-ov-file#puppetboard"
click OpenVoxServer "https://github.com/OpenVoxProject/openvox-server?tab=readme-ov-file#puppet-server"
click Agent1 "https://github.com/OpenVoxProject/openvox-agent?tab=readme-ov-file#the-puppet-agent"
click Agent2 "https://github.com/OpenVoxProject/openvox-agent?tab=readme-ov-file#the-puppet-agent"
click Agent_n "https://github.com/OpenVoxProject/openvox-agent?tab=readme-ov-file#the-puppet-agent"
click Foreman "<https://www.theforeman.org/>"
click Webhook "<https://github.com/voxpupuli/webhook-go?tab=readme-ov-file#webhook-go>"
click OpenVoxDB "<https://github.com/OpenVoxProject/openvoxdb>"
click HDM "<https://github.com/betadots/hdm?tab=readme-ov-file#hdm---hiera-data-manager>"
click Puppetboard "<https://github.com/voxpupuli/puppetboard?tab=readme-ov-file#puppetboard>"
click OpenVoxServer "<https://github.com/OpenVoxProject/openvox-server?tab=readme-ov-file#puppet-server>"
click Agent1 "<https://github.com/OpenVoxProject/openvox-agent?tab=readme-ov-file#the-puppet-agent>"
click Agent2 "<https://github.com/OpenVoxProject/openvox-agent?tab=readme-ov-file#the-puppet-agent>"
click Agent_n "<https://github.com/OpenVoxProject/openvox-agent?tab=readme-ov-file#the-puppet-agent>"
</div>

## Setup and Usage
Expand All @@ -59,7 +59,6 @@ We recommend organizing your code as a Control Repository with branches for
environments. See the [reference repository](https://github.com/puppetlabs/control-repo)
for an example.


### Foreman

[Foreman](https://www.theforeman.org) is a complete lifecycle management tool
Expand All @@ -68,7 +67,6 @@ classifier, a Hiera data source, and report monitoring. It also includes the
power to easily automate repetitive tasks, quickly deploy applications, and
proactively manage servers, on-premise or in the cloud.


### Puppet Webhook

Vox Pupuli offers [webhook-go](https://github.com/voxpupuli/webhook-go?tab=readme-ov-file#webhook-go), an open source ([Apache-2.0 licensed](https://github.com/voxpupuli/webhook-go/blob/master/LICENSE)) webhook that can listen for events from:
Expand All @@ -93,24 +91,23 @@ Install it on your server in your infrastructure and use it to deploy your contr

If you're a Golang shop, you might consider [g10k](https://github.com/xorpaul/g10k) as well.


### OpenVox Stack

We recommend managing each of these components with the supported module.

* OpenVoxDB
* [puppetlabs/puppetdb](https://forge.puppet.com/puppetlabs/puppetdb)
Copy link
Member

@binford2k binford2k Aug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't hurt to have deeper indentation steps and it often makes it easier to read.

* The default PostgreSQL database is recommended.
* [puppetlabs/puppetdb](https://forge.puppet.com/puppetlabs/puppetdb)
* The default PostgreSQL database is recommended.
* OpenVoxServer and agents
* [theforeman/puppet](https://forge.puppet.com/modules/theforeman/puppet)
* [theforeman/puppet](https://forge.puppet.com/modules/theforeman/puppet)
* Hiera Data Manager (HDM)
* [puppet/hdm](https://forge.puppet.com/modules/puppet/hdm)
* [puppet/hdm](https://forge.puppet.com/modules/puppet/hdm)
* r10k & webhook-go
* [puppet/r10k](https://forge.puppet.com/modules/puppet/r10k/readme)
* [puppet/r10k](https://forge.puppet.com/modules/puppet/r10k/readme)
* nftables firewalling
* [puppet/nftables](https://forge.puppet.com/modules/puppet/nftables/readme)
* [puppet/nftables](https://forge.puppet.com/modules/puppet/nftables/readme)
* [InfluxDB](https://www.influxdata.com/products/influxdb/), [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) & [Grafana](https://grafana.com/oss/grafana/) for monitoring
* [puppetlabs/puppet_operational_dashboards](https://forge.puppet.com/modules/puppetlabs/puppet_operational_dashboards/readme) (ships ready to use dashboards)
* [puppetlabs/puppet_operational_dashboards](https://forge.puppet.com/modules/puppetlabs/puppet_operational_dashboards/readme) (ships ready to use dashboards)

## Scaleout options

Expand Down
42 changes: 25 additions & 17 deletions _docs/extending-expired-ca-cert.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ The script performs the following steps:
1. Sets up a temporary SSL environment.
2. Generates a new CA certificate with the expiration set 15 years into the future.
3. Writes the new certificate to the directory returned by:
```

```shell
puppet config print --section master cacert
```

Expand All @@ -27,22 +28,28 @@ The new file will be named using the format: `ca_crt-expires-<NEW_END_DATE>.pem`
## Steps after running the script

1. Examine the end date of the new certificate by executing:
```
openssl x509 -in <PATH_TO_NEW_KEY> -noout -subject -issuer -enddate
```
Confirm the issuer matches your existing CA and that the expiration date is 15 years in the future.
2. Back up the current certificate and install the new one:
```
# Assuming the directory where the CA is stored is /etc/puppetlabs/puppet/ssl/ca
mv /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem.bak.$(date +%F)
mv <PATH_TO_NEW_KEY> /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem
```
3. Restart the OpenVox server.
```
systemctl restart puppetserver
```

# OpenVox agents
```shell
openssl x509 -in <PATH_TO_NEW_KEY> -noout -subject -issuer -enddate
```

Confirm the issuer matches your existing CA and that the expiration date is 15 years in the future.

1. Back up the current certificate and install the new one:

```shell
# Assuming the directory where the CA is stored is /etc/puppetlabs/puppet/ssl/ca
mv /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem.bak.$(date +%F)
mv <PATH_TO_NEW_KEY> /etc/puppetlabs/puppet/ssl/ca/ca_crt.pem
```

1. Restart the OpenVox server.

```shell
systemctl restart puppetserver
```

## OpenVox agents

The following assumes the CA certificate is stored in the default location:
`/etc/puppetlabs/puppet/ssl/certs/ca.pem`.
Expand All @@ -52,13 +59,14 @@ The following assumes the CA certificate is stored in the default location:
The new certificate can be downloaded via the HTTP API using the following
command:

```
```shell
curl https://<PUPPET-CA-HOST>:8140/puppet-ca/v1/certificate/ca --insecure > /etc/puppetlabs/puppet/ssl/certs/ca.pem
```

A command similar to the above would need to be orchestrated across all of your agents.

## OpenVox agents on version 8 and newer

Agents running Puppet 8+ will automatically fetch the updated CA certificate according to the [ca_refresh_interval](https://github.com/OpenVoxProject/openvox/blob/main/references/configuration.md#ca_refresh_interval) setting.

## Older agents
Expand Down
65 changes: 32 additions & 33 deletions _docs/how_to_run_tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,26 @@ summary: A description of how to run the Vox Pupuli test suite for Puppet module
---

- [Running the tests in a local ruby environment](#running-the-tests-in-a-local-ruby-environment)
* [Installing dependencies](#installing-dependencies)
Copy link
Member

@binford2k binford2k Aug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's entirely valid and useful to use different markers to indicate list depth.

* [Vox Pupuli helpers](#vox-pupuli-helpers)
* [Linting](#linting)
* [REFERENCE.md update](#referencemd-update)
* [Unit tests](#unit-tests)
+ [Detailed sub tasks](#detailed-sub-tasks)
* [Running Acceptance Tests](#running-acceptance-tests)
+ [Beaker hypervisors](#beaker-hypervisors)
+ [Environment variables and hostnames](#environment-variables-and-hostnames)
+ [Getting setfiles for a module](#getting-setfiles-for-a-module)
+ [Running Beaker](#running-beaker)
+ [Custom Facts](#custom-facts)
+ [Run a specific test](#run-a-specific-test)
- [Installing dependencies](#installing-dependencies)
- [Vox Pupuli helpers](#vox-pupuli-helpers)
- [Linting](#linting)
- [REFERENCE.md update](#referencemd-update)
- [Unit tests](#unit-tests)
- [Detailed sub tasks](#detailed-sub-tasks)
- [Running Acceptance Tests](#running-acceptance-tests)
- [Beaker hypervisors](#beaker-hypervisors)
- [Environment variables and hostnames](#environment-variables-and-hostnames)
- [Getting setfiles for a module](#getting-setfiles-for-a-module)
- [Running Beaker](#running-beaker)
- [Custom Facts](#custom-facts)
- [Run a specific test](#run-a-specific-test)
- [Running the tests in the VoxBox container](#running-the-tests-in-the-voxbox-container)
* [Installation](#installation)
* [Linting](#linting-in-voxbox)
* [Rubocop](#rubocop)
* [Unit tests](#unit-tests-in-voxbox)
* [REFERENCE.md update](#referencemd-update-in-voxbox)
* [Puppetfile](#puppetfile)
- [Installation](#installation)
- [Linting](#linting-in-voxbox)
- [Rubocop](#rubocop)
- [Unit tests](#unit-tests-in-voxbox)
- [REFERENCE.md update](#referencemd-update-in-voxbox)
- [Puppetfile](#puppetfile)

The testing and development tools have a bunch of dependencies, all managed by [bundler](http://bundler.io/).
By default the tests use the latest version of Puppet.
Expand Down Expand Up @@ -88,9 +88,9 @@ If you don't know if you need to install or update gems, you can just add `bundl
Check out the following page if you want to add a test suite to your module or want
to learn more about the Vox Pupuli test helpers:

* [voxpupuli-test](https://github.com/voxpupuli/voxpupuli-test) for unit testing
Copy link
Member

@binford2k binford2k Aug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the intent of this list is perfectly clear, even if another part of the doc used a different marker

* [voxpupuli-acceptance](https://github.com/voxpupuli/voxpupuli-acceptance) for acceptance testing
* [voxpupuli-release](https://github.com/voxpupuli/voxpupuli-release) for creating a release
- [voxpupuli-test](https://github.com/voxpupuli/voxpupuli-test) for unit testing
- [voxpupuli-acceptance](https://github.com/voxpupuli/voxpupuli-acceptance) for acceptance testing
- [voxpupuli-release](https://github.com/voxpupuli/voxpupuli-release) for creating a release

### Linting

Expand Down Expand Up @@ -201,18 +201,18 @@ _Remember to add your user to the group that allows access to docker/libvirt._

For Vox Pupuli's acceptance testing suite, Beaker is managed by a set of environment variables.

* `BEAKER_HYPERVISOR` Sets the Hypervisor, `vagrant` or `vagrant_libvirt` for VM based testing
- `BEAKER_HYPERVISOR` Sets the Hypervisor, `vagrant` or `vagrant_libvirt` for VM based testing
It is a good idea to export the `BEAKER_HYPERVISOR` variable in your shell configuration.
* `BEAKER_DESTROY` Should the test environment be removed at the end of a test
* `BEAKER_DESTROY=onpass` Only removes the environment if everything passes, allowing review of the system in the state it was in when the test suite failed.
* `BEAKER_DESTROY=no` Always leave an artifact, which likely will break future runs without cleanup.
* `BEAKER_DESTROY=yes` _(DEFAULT)_ always clean up.
* `BEAKER_PROVISION` Should we ensure a clean system is built to run the suite.
* If `BEAKER_DESTROY` is set to no, `BEAKER_PROVISION=yes` will fail the run (because of the existing box/container)
* If `BEAKER_DESTROY` is set to no, `BEAKER_PROVISION=no` will run the test suite against the system anyways, which may cause environmental issues if the test suite doesn't perfectly put things to a default state.
- `BEAKER_DESTROY` Should the test environment be removed at the end of a test
- `BEAKER_DESTROY=onpass` Only removes the environment if everything passes, allowing review of the system in the state it was in when the test suite failed.
- `BEAKER_DESTROY=no` Always leave an artifact, which likely will break future runs without cleanup.
- `BEAKER_DESTROY=yes` _(DEFAULT)_ always clean up.
- `BEAKER_PROVISION` Should we ensure a clean system is built to run the suite.
- If `BEAKER_DESTROY` is set to no, `BEAKER_PROVISION=yes` will fail the run (because of the existing box/container)
- If `BEAKER_DESTROY` is set to no, `BEAKER_PROVISION=no` will run the test suite against the system anyways, which may cause environmental issues if the test suite doesn't perfectly put things to a default state.

* `BEAKER_SETFILE` What should we be testing. Beaker will call beaker-hostgenerator to create a defaultconfiguration based on this, using the known configurations for Vox Pupuli.
* `BEAKER_PUPPET_COLLECTION` What implementation and version of Puppet are we testing against
- `BEAKER_SETFILE` What should we be testing. Beaker will call beaker-hostgenerator to create a defaultconfiguration based on this, using the known configurations for Vox Pupuli.
- `BEAKER_PUPPET_COLLECTION` What implementation and version of Puppet are we testing against

These are all defined in [voxpupuli-acceptance](https://github.com/voxpupuli/voxpupuli-acceptance/#running-tests) to review how they are used and more specialized features.

Expand Down Expand Up @@ -286,7 +286,6 @@ BEAKER_SETFILE="almalinux9-64{hostname=almalinux9-64-puppet8.example.com}" bundl

If you need to run tests against a different version or implementation of OpenVox (or Puppet) you can either `export BEAKER_PUPPET_COLLECTION="openvox7"` or add `BEAKER_PUPPET_COLLECTION="openvox7"` to your command line.


```shell
BEAKER_PUPPET_COLLECTION="openvox7" BEAKER_SETFILE="ubuntu2404-64" bundle exec rake beaker
```
Expand Down
Loading