asciidoctor/asciidoctor-intellij-plugin

Link Checker on documentation site

Open

#663 opened on Feb 7, 2021

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Java (155 forks)auto 404
documentationenhancementhelp wanted

Repository metrics

Stars
 (392 stars)
PR merge metrics
 (PR metrics pending)

Description

Why the new feature should be added

When the user clicks on a link on the documentation site, they expect it to work and it should not produce a 404.

If a link has changed and the target site redirects to a new page today, we should know about it to update the link, as it might no longer forward the link tomorrow.

How the new feature should work

The documentation site should have all internal links working, external should work as well as well (but might be unavailable at time of build).

There are tools like https://linkchecker.github.io/linkchecker/ that can be part of the build.

There are multiple places where this could be integrated:

  • as a GitHub action on the main repo (then it would give immediate feedback on pull requests, but not block the docs build)
  • on the builds in the docs repo, maybe even when it runs on Netlify (then it would block publishing of the docs).

Contributor guide

Research direction
Evaluate integrating a link checker tool (e.g., linkchecker) into the GitHub Actions workflow or Netlify build to verify internal and external links on the documentation site.
Tech stack
None
Domain
documentation
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Mostly clear
Prerequisites
GitCI/CD
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65