Docsource

Download • Getting Started

Command-line interface that detects broken links within Markdown documentation files.

Table of Contents

• Download
• Getting Started
  • Supported Frameworks
  • Links
    • External Links
    • Relative Links
    • Mailto Links
• Usage
  • Scan
    • All Absolute
    • Content Directory
    • Image Directory
    • Index Filename
• Continuous Integration
  • GitLab CI/CD
• FAQ
• Motivation

Download

You can download Docsource from the GitHub releases page. It is available in three different formats:

• JAR (requires Java 21)
• Windows
• Linux

Additionally, a Docker image is available on Docker Hub.

Getting Started

Docsource should be run from the root directory of your documentation.

docsource scan --recursive . 

Supported Frameworks

Docsource tries to detect the framework used to generate the documentation and applies the appropriate configuration. The supported and tested frameworks are:

• Docsify
• Hugo

Links

Docsource can check three types of Markdown links: external links, relative links, and mailto links.

External Links

External links point to an external domain. Docsource sends an HTTP request and check the HTTP return code:

• The link is considered broken if the return code is 404.
• The link is considered valid if the return code is anything other than 404.

Relative Links

Relative links point to the same domain. Docsource checks if the linked resource actually exists:

• The link is considered broken if the linked resource does not exist.
• The link is considered valid if the linked resource exists.

A relative link can be either absolute or relative:

• Absolute links are checked from the current user directory (i.e., the root directory of the documentation) concatenated with the content directory if provided (--content-directory) or the image directory for images if provided (--image-directory).
• Relative links are checked from the file the link belongs to.

Mailto Links

Mailto links point to an email address. Docsource checks the format of the email address:

• The link is considered broken if the format is incorrect.
• The link is considered valid if the format is correct.

Usage

Scan

  ____
 (|   \
  |    | __   __   ,   __          ,_    __   _
 _|    |/  \_/    / \_/  \_|   |  /  |  /    |/
(/\___/ \__/ \___/ \/ \__/  \_/|_/   |_/\___/|__/

Usage: docsource scan [-AhIkrvV] [--skip-external] [--skip-mailto] [--skip-relative] [--content-directory=<contentDirectory>]
                [--image-directory=<imageDirectory>] [--index-filename=<indexFilename>] [files...]

Description:

Scan documentation.

Parameters:
      [files...]         Root directories or files to scan.

Options:
  -A, --all-absolute     Consider relative paths as absolute paths.
      --content-directory=<contentDirectory>
                         Specify a sub-directory of the root directory containing the Markdown files. E.g., 'content' for Hugo.
  -h, --help             Show this help message and exit.
  -I, --image-absolute   Consider relative image paths as absolute paths.
      --image-directory=<imageDirectory>
                         Specify a sub-directory of the root directory containing the images. E.g., 'static' for Hugo.
      --index-filename=<indexFilename>
                         Specify the filename to use as an index file. E.g., '_index.md' for Hugo.
  -k, --insecure         Turn off hostname and certificate chain verification.
  -r, --recursive        Scan directories recursively.
      --skip-external    Skip external links.
      --skip-mailto      Skip mailto links.
      --skip-relative    Skip relative links.
  -v, --verbose          Enable the verbose mode.
  -V, --version          Print version information and exit.

Scan is used to scan Markdown files in your documentation to detect broken links. The command should be run from the root folder of your documentation.

All Absolute (--all-absolute)

If you need to check relative link paths as absolute paths rather than from the file the link belongs to, you can use the --all-absolute option.

Content Directory (--content-directory)

If the documentation is located in a subdirectory of the root directory, you can specify the content directory using the --content-directory option.

E.g., for Hugo, the content directory is content.

Image Directory (--image-directory)

If the images are located in a subdirectory of the root directory, you can specify the image directory using the --image-directory option.

E.g., for Hugo, the image directory is static.

Index Filename (--index-filename)

If the documentation uses a specific filename as an index file, you can specify the index filename using the --index-filename option.

E.g., for Hugo, the index filename is _index.md.

Continuous Integration

GitLab CI/CD

Docsource can be run in a GitLab pipeline using the Docker image.

check links:
  stage: verify 🩺
  image: loicgreffier/docsource
  script:
    - docsource scan --recursive .

Frequently Asked Questions (FAQ)

How can Docsource trust my SSL certificates

How can Docsource trust my SSL certificates

You can make Docsource trust your SSL certificates if you need it.

If you use the JAR, add your SSL certificates in the JVM cacerts.

If you use the native executables, you can load a trust store dynamically at runtime as specified by GraalVM.

docsource scan . -Djavax.net.ssl.trustStore=pathToTheTrustStore -Djavax.net.ssl.trustStorePassword=trustStorePassword

Motivation

Maintaining documentation with tens or hundreds of pages can be a pain, and there's nothing more frustrating for readers than encountering broken links. Docsource helps keep documentation up-to-date and detects broken links.

It was also an opportunity to test out Spring Native!