Add Fenced Div and Link Validation Step

[zkamvar]

Summary

This PR adds pre-build lesson validation for the following elements:

• Fenced Divs
• Internal Links (including images)
• Image Alt Text
• Link Text

These are implemented for both serve() (which implies build_lesson()) and
ci_deploy() (which will produce warnings in a manner that GitHub will understand and point to the line in the file).

This PR will fix #254

Testing

To test this PR, use:

remotes::install_github("carpentries/sandpaper#255")
library("sandpaper")

Examples

This is something you might see when you have a link that points to a file that doesn’t exist:

sandpaper::validate_lesson("~/Documents/Carpentries/Git/carpentries/sandpaper-docs/")
#> ── Validating Fenced Divs ──────────────────────────────────────────────────────
#> ── Validating Internal Links and Images ────────────────────────────────────────
#> ! There were errors in 1/68 links
#> 
#> - Some linked internal files do not exist
#> 
#> episodes/introduction.md:171  [missing file] sandpaper.md

^{Created on 2022-02-17 by the reprex package (v2.0.1)}

Including `heading = TRUE` (is a bit noisy)

sandpaper::validate_lesson("~/Documents/Carpentries/Git/carpentries/sandpaper-docs/", headings = TRUE)
#> ── Validating Headings ─────────────────────────────────────────────────────────
#> ── Heading structure ───────────────────────────────────────────────────────────
#> # Episode: "Introduction to The Carpentries Workbench" 
#> ├─### Takeaway message  (must be level 2)
#> ├─## Super Quickstart: Copy A Template from GitHub 
#> │ ├─### Step 1: Choose a template 
#> │ ├─### Step 2: Choose a name for your lesson repository. 
#> │ │ └─#### Creating a new lesson repository 
#> │ └─### Step 3: Deploy the site 
#> ├─### Step 2: Choose a name for your lesson repository. 
#> ├─## Quickstart: Create a New Lesson 
#> │ ├─### Create a Lesson Locally 
#> │ └─### :beetle: Known Quirk 
#> ├─## Previewing Your New Lesson {#preview} 
#> │ ├─### What's with the :: syntax? 
#> │ ├─### DID YOU KNOW? Keyboard Shortcuts are Available 
#> │ ├─### How do I determine the order of files displayed on the website? 
#> │ └─### Set the schedule (optional) 
#> ├─## Warning Message 
#> ├─## Push to GitHub 
#> │ ├─### :hourglass: Be Patient 
#> │ └─### Alternative: Two-step solution in R 
#> └─## Tools
#> ────────────────────────────────────────────────────────────────────────────────
#> ── Heading structure ───────────────────────────────────────────────────────────
#> # Episode: "Maintaining a Healthy Infrastructure" 
#> ├─## Introduction 
#> ├─## Maintainer Tools 
#> ├─## Validator 
#> ├─## Styling 
#> ├─## Deployment 
#> │ ├─### Updating Your Deployment Workflows 
#> │ │ └─#### :construction: Under Development  (must be level 2)
#> │ ├─### On Schedule (default) 
#> │ ├─### Via GitHub 
#> │ └─### Via R 
#> │   └─#### Do not combine workflow changes with other changes 
#> ├─### Updating Your Deployment Workflows 
#> └─### Via R
#> ────────────────────────────────────────────────────────────────────────────────
#> ── Heading structure ───────────────────────────────────────────────────────────
#> # Episode: "Auditing Pull Requests" 
#> ├─#### :construction: Under Development  (must be level 2)
#> ├─## Introduction 
#> ├─## Reviewing A Pull Request 
#> │ ├─### Living with Entropy 
#> │ └─### Risk Management 
#> └─## Automated Pull Requests 
#>   ├─### For Lessons Outside of The Carpentries 
#>   ├─### Workflow Updates 
#>   └─### Updating Package Cache
#> ────────────────────────────────────────────────────────────────────────────────
#> ! There were errors in 3/86 headings
#> 
#> - First heading must be level 2
#> <https://webaim.org/techniques/semanticstructure/#headings>
#> 
#> episodes/introduction.md:34  (must be level 2)
#> episodes/update.md:25  (must be level 2)
#> episodes/pull-request.md:26  (must be level 2)
#> ── Validating Fenced Divs ──────────────────────────────────────────────────────
#> ── Validating Internal Links and Images ────────────────────────────────────────
#> ! There were errors in 1/68 links
#> 
#> - Some linked internal files do not exist
#> 
#> episodes/introduction.md:171  [missing file] sandpaper.md

^{Created on 2022-02-17 by the reprex package (v2.0.1)}

[tobyhodges]

── Validating Fenced Divs ──────────────────────────────────────────────────────────────────────────
! There were errors in 1/89 fenced divs

- The Carpentries Workbench knows the following div types callout, objectives, questions, challenge, prereq, checklist, solution, hint, discussion, testimonial, keypoints, instructor

episodes/07-infrastructure.md:45  [unknown div] exercise
── Validating Internal Links and Images ────────────────────────────────────────────────────────────
! There were errors in 16/34 links

- Links must use HTTPS <https://https.cio.gov/everything/>
- Some linked internal files do not exist
- Images need alt-text <https://webaim.org/techniques/hypertext/link_text#alt_link>
- Avoid uninformative link phrases <https://webaim.org/techniques/hypertext/link_text#uninformative>
- Avoid single-letter or missing link text <https://webaim.org/techniques/hypertext/link_text#link_length>

episodes/03-audience.md:NA  [text too short] ‘1’
episodes/03-audience.md:NA  [text too short] ‘2’
episodes/05-objectives.md:61  [text too short] ‘1’
episodes/05-objectives.md:NA  [text too short] ‘1’
episodes/07-infrastructure.md:57  [uninformative text] ‘click here’
episodes/07-infrastructure.md:58  [missing alt-text]
episodes/07-infrastructure.md:59  [missing file] ../imaginary.html
episodes/11-exercises.md:24  [needs HTTPS] http://teachtogether.tech/en/index.html#s:exercises
episodes/11-exercises.md:51  [needs HTTPS] http://teachtogether.tech/en/index.html#s:exercises
episodes/11-exercises.md:53  [needs HTTPS] http://teachtogether.tech/en/index.html#fill-in-the-blanks
episodes/11-exercises.md:54  [needs HTTPS] http://teachtogether.tech/en/index.html#parsons-problem
episodes/11-exercises.md:55  [needs HTTPS] http://teachtogether.tech/en/index.html#minimal-fix
episodes/11-exercises.md:NA  [needs HTTPS] http://teachtogether.tech/en/index.html#fill-in-the-blanks
episodes/11-exercises.md:NA  [needs HTTPS] http://teachtogether.tech/en/index.html#parsons-problem
episodes/11-exercises.md:NA  [needs HTTPS] http://teachtogether.tech/en/index.html#minimal-fix
episodes/18-preparing.md:91  [missing file] _extras/trial-runs.md

Yep it works and has already helped me identify several things that had slipped through/accessibility improvements 🙌 I should have recognised the intentional addition of issues to be detected as the act of hubris it was 😆 Thanks @zkamvar!

The only improvement I can suggest is to make the reasons given even more explicit, e.g. [link text too short] instead of [text too short] etc. If I can find the appropriate place in the source code, I will make suggestions there.

[zkamvar]

Yep it works and has already helped me identify several things that had slipped through/accessibility improvements 🙌

That's wonderful! I will note that some of these are false positives (all the items with missing line numbers are actually labels for anchor links), but I will address them on the {pegboard} end.

[zkamvar]

@tobyhodges would you be willing to give this your approval for merging?

[tobyhodges]

Right, yes. Approved now. Thanks for your patience!

[zkamvar]

No patience was required on my part! Thank you for testing this out!