Merge pull request #8 from osg-htc/docs/markdownlint-fixes-1

docs(lint): initial markdownlint fixes — add top-level headings and s…

Author: ShawnMcKee

.github/PR_BODY.md

@@ -1,24 +1,31 @@
-Reorganize docs into persona-driven structure (Quick Deploy, Troubleshooter, Researcher)
+
+# Reorganize docs into persona-driven structure (Quick Deploy, Troubleshooter, Researcher)
 
 Summary
-- This branch scaffolds a persona-driven documentation layout under `docs/personas/` and adds templates and feature pages.
-- Adds tooling to detect and safely repair broken links (`docs/tools/`). A broken-links report was generated and partially applied; backups are available under `docs/.link_check_backups/`.
-- Adds a GitHub Actions workflow to run linting and build the MkDocs site and to run the docs link-check script in dry-run mode.
+
+This branch scaffolds a persona-driven documentation layout under `docs/personas/` and adds templates and feature pages.
+
+Adds tooling to detect and safely repair broken links (`docs/tools/`). A broken-links report was generated and partially applied; backups are available under `docs/.link_check_backups/`.
+
+Adds a GitHub Actions workflow to run linting and build the MkDocs site and to run the docs link-check script in dry-run mode.
 
 Files changed / added (high level)
+
 - `docs/personas/` (landing pages and starters)
 - `docs/features/` (feature guidance pages)
 - `docs/templates/` (author templates)
 - `docs/tools/` (link-checker and applier)
 - `.github/workflows/docs-ci.yml` (this CI workflow)
 
 Checklist
+
 - [ ] Review content in `docs/personas/` and move or expand Quick Deploy quickstarts as needed
 - [ ] Confirm link mapping entries in `docs/tools/link_mapping.json`
 - [ ] Review mkdocs nav in `mkdocs.yml` and add any missing pages intentionally omitted
 - [ ] Run the link-checker locally for a full (non-dry-run) pass before merging if you want the applier to touch files automatically
 
 Notes
+
 - The CI runs `mkdocs build --strict` so build warnings will fail the job. It also runs the link-checker in dry-run mode so PRs will report issues but not modify files.
 - If you want the CI to automatically apply safe mapping changes, we should add a separate job with a bot account and commit permissions (not present in this workflow).
 

docs/network-troubleshooting.md

@@ -1,15 +1,13 @@
-<span class="twiki-macro LINKCSS"></span>
+# Network and Network Troubleshooting Documentation
 
-<span class="twiki-macro SPACEOUT">Network  and Network Troubleshooting Documentation</span>
-============================================================================================
+<span class="twiki-macro STARTINCLUDE"></span>
 
+This page will eventually include pointers to various network troubleshooting resources. In general, when users suspect a network problem the procedure is:
 
-<span class="twiki-macro STARTINCLUDE"></span> This page will eventually include pointers to various network troubleshooting resources. In general, when users suspect a network problem the procedure is:
-
--   **Document the problem**: Basically you need to describe the problem you encountered. Provide any relevant details like the exact command you used, any errors or warning you got and any problems you observed. This can help you better understand the problem and will allow you to easily "hand-off" troubleshooting to an expert
--   **Gather relevant data:** Run tests (see Guide below) and capture the results.
--   **Contact your local network support** (this is sometimes where users don't know where to go). Google or your campus web-pages should be able to help you find the right contact.
--   **Escalate**, if the problem persists (See below)
+- **Document the problem**: Basically you need to describe the problem you encountered. Provide any relevant details like the exact command you used, any errors or warning you got and any problems you observed. This can help you better understand the problem and will allow you to easily "hand-off" troubleshooting to an expert
+- **Gather relevant data:** Run tests (see Guide below) and capture the results.
+- **Contact your local network support** (this is sometimes where users don't know where to go). Google or your campus web-pages should be able to help you find the right contact.
+- **Escalate**, if the problem persists (See below)
 
 ESnet maintains a very useful page on network troubleshooting at <https://fasterdata.es.net/performance-testing/troubleshooting/>
 

docs/osg-network-analytics.md

@@ -1,2 +1,4 @@
+# OSG Network Analytics
+
 - **OSG Analytics platform** <http://atlas-kibana.mwt2.org/s/networking/app/kibana#/dashboard/Default?_g=()>
 - **WLCG dashboards** <https://monit-grafana-open.cern.ch/d/000000523/home?orgId=16>

docs/osg-network-services.md

@@ -1,9 +1,9 @@
-### OSG Network Services
+# OSG Network Services
 
 Open Science Grid is providing a number of network-related services to support its members and collaborators in monitoring, understanding, measuring, diagnosing and managing the networks
 used to support their work.
 
 Here we will provide an overview of the OSG network services and where to find more information.
 
-Much of the work to create effective analytics is being done in the NSF funded SAND project (http://sand-ci.org/) which is exploring technologies and methodologies to analyze, summarize and visualize the various networking metrics we have available in the OSG networking data pipeline.   As some of these tools and dashboards become production ready, we will add them to this documentation.
+Much of the work to create effective analytics is being done in the NSF funded [SAND project](http://sand-ci.org/) which is exploring technologies and methodologies to analyze, summarize and visualize the various networking metrics we have available in the OSG networking data pipeline. As some of these tools and dashboards become production ready, we will add them to this documentation.
 

docs/perfsonar-in-osg.md

@@ -1,4 +1,4 @@
-### Overview of perfSONAR
+# Overview of perfSONAR
 
 For those not familiar with `perfSONAR`, this page provides a quick overview of what it is and why we recommend its deployment at OSG and WLCG sites.
 

docs/perfsonar/deployment-models.md

@@ -1,4 +1,4 @@
-### perfSONAR Deployment Options
+# perfSONAR Deployment Options
 
 The primary motivation for perfSONAR deployment is to test isolation, i.e. only one end-to-end test should run on a host at a time. This ensures that the test results are not impacted by the other tests. Otherwise it is much more difficult to interpret test results, which may vary due to host effects rather then network effects. Taking this into account it means that perfSONAR measurement tools are much more accurate running on a dedicated hardware and while it may be useful to run them on other hosts such as Data Transfer Nodes the current recommendation is to have specific measurement machine. In addition, as bandwidth testing could impact latency testing, we recommend to deploy two different nodes, each focused on specific set of tests. The following deployment options are currently available:
 

docs/perfsonar/faq.md

@@ -1,4 +1,4 @@
-### Frequently Asked Questions 
+ # Frequently Asked Questions
 
 Here we will provide details on troubleshooting perfSONAR installations for OSG and WLCG as well as some additional configuration options and a FAQ.
 

docs/perfsonar/installation.md

@@ -1,4 +1,4 @@
-## perfSONAR Installation Guide
+# perfSONAR Installation Guide
 
 !!! note
     This page has older instructions for non-containerized perfSONAR deployments which are, as of October 2025, no longer the recommended best practice.

docs/perfsonar/psetf.md

@@ -1,5 +1,5 @@
 
-### Infrastructure Monitoring
+# Infrastructure Monitoring
 
 WLCG/OSG is operating more than 200 perfSONAR agents world-wide. A typical perfSONAR deployment has many services that need to function correctly for the the system to work.  As we scale-up to many perfSONAR deployments across many sites it can be
 difficult to verify everything is working correctly.