Skip to content

Latest commit

 

History

History
101 lines (72 loc) · 3.59 KB

README-checklinks.markdown

File metadata and controls

101 lines (72 loc) · 3.59 KB
Raw

checklinks

checklinks is a node.js script based upon the remark-validate-links tool. It validates all internal links (i.e., foobar).

Install

The tool has a few node.js requirements. If you already have node installed on your system, run:

npm install

in the documentation directory.

Usage

./checklinks [directory]

This will validate internal link references on all files ending with .md in the repository. If invalid links are found, an error message is shown with details about the invalid link, and an error code is returned.

Output

mender-docs: ./checklink 
Do not fail on missing sections in API links
Do not fail on missing sections in API links
Do not fail on missing sections in API links
01.Getting-started/02.On-premise-installation/docs.md
  13:146-13:224  warning  Link to unknown file: `../01.uickstart-with-raspberry-pi/docs.md`. Did you mean `../01.Quickstart-with-raspberry-pi/docs.md`  missing-file  remark-validate-links

⚠ 1 warning

Ignoring paths

The link-checker has the ability to ignore failing links to certain files, by adding the absolute path to the file .checklinks-whitelist. The paths field is used to ignore missing headers while on an existing section and the files filed is used to ignore missing files.

As such, all links pointing to the 200.Server-side-API section and all files in 302.Release-information/01.Release-notes-changelog are ignored by default, as these sections are generated independently from mender-api-docs and mender-docs-changelog repositories respectively.

Note

A few things to keep in mind:

  • The checker does not verify sections in the 200.Server-side-API folder, as this section is generated independently from mender-api-docs repo, and not present when the tool is run.
  • The header slug is a modified Github header slugger, which collapses multiple dashes into one. That is slug(---) -> slug(-). This is because Grav, which our documentation uses does not fully support the Github slug format.

didyoumean -- Automatic broken link fixing

didyoumean is a simple script which helps migrating sections in the documentation with the help of the checklinks script.

The script takes the output from checklinks, which can be on the form:

02.Overview/01.Introduction/docs.md
  30:433-30:573  warning  Link to unknown heading in `../../04.Artifacts/10.Yocto-project/02.Image-configuration/docs.md`: `disabling-mender-s-a-system-service`. Did you mean `disabling-mender-as-a-system-service`  missing-heading-in-file  remark-validate-links

1 warning

Notice the Did you mean part. This is output from the checklinks script if the string distance between the erronous link, and a valid link is close enough.

Thus, this can be taken advantage of by the didyoumean script. The script will automatically rewrite all the suggested links:

checklinks |& bash ./scripts/didyoumean

Resulting in a successfully migrated section.

If unsuccesful

If the string distance is too big, the checklinks is unable to guess the replacement candidate, and obviously, the didyoumean script is unable to fill in the replacement. In this instance, the replacement must be done by hand. A recommendation is to script this also. Most modern editors have some sort of server support, which means it enables you to open a buffer of a given file, with the cursor at a given line and column.

For Emacs this would be something like:

emacsclient +<line>:<column> <filepath>