{"id":25527575,"url":"https://github.com/loicgreffier/docsource","last_synced_at":"2025-07-09T04:06:00.890Z","repository":{"id":65679331,"uuid":"573588423","full_name":"loicgreffier/docsource","owner":"loicgreffier","description":"Command-line interface for detecting broken links in Markdown documentation files.","archived":false,"fork":false,"pushed_at":"2025-06-20T21:39:07.000Z","size":577,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-20T22:30:06.403Z","etag":null,"topics":["cli","documentation","graalvm-native-image","markdown","spring-boot","spring-native"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loicgreffier.png","metadata":{"files":{"readme":"README.md","changelog":"changelog-builder.json","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-12-02T20:45:17.000Z","updated_at":"2025-06-20T21:39:10.000Z","dependencies_parsed_at":"2024-01-02T09:28:25.947Z","dependency_job_id":"b49c7f3b-73f4-4988-b017-dc279cf2c26c","html_url":"https://github.com/loicgreffier/docsource","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/loicgreffier/docsource","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loicgreffier%2Fdocsource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loicgreffier%2Fdocsource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loicgreffier%2Fdocsource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loicgreffier%2Fdocsource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loicgreffier","download_url":"https://codeload.github.com/loicgreffier/docsource/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loicgreffier%2Fdocsource/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264390706,"owners_count":23600562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","documentation","graalvm-native-image","markdown","spring-boot","spring-native"],"created_at":"2025-02-19T22:20:07.204Z","updated_at":"2025-07-09T04:06:00.884Z","avatar_url":"https://github.com/loicgreffier.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\".readme/logo.svg\" alt=\"Docsource\"/\u003e\n\n# Docsource\n\n[![GitHub Build](https://img.shields.io/github/actions/workflow/status/loicgreffier/docsource/build.yml?branch=main\u0026logo=github\u0026style=for-the-badge)](https://github.com/loicgreffier/docsource/actions/workflows/build.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/loicgreffier/docsource?logo=github\u0026style=for-the-badge)](https://github.com/loicgreffier/docsource/releases)\n[![GitHub Stars](https://img.shields.io/github/stars/loicgreffier/docsource?logo=github\u0026style=for-the-badge)](https://github.com/loicgreffier/docsource)\n[![Docker Pulls](https://img.shields.io/docker/pulls/loicgreffier/docsource?label=Pulls\u0026logo=docker\u0026style=for-the-badge)](https://hub.docker.com/r/loicgreffier/docsource/tags)\n[![SonarCloud Coverage](https://img.shields.io/sonar/coverage/loicgreffier_docsource?logo=sonarcloud\u0026server=https%3A%2F%2Fsonarcloud.io\u0026style=for-the-badge)](https://sonarcloud.io/component_measures?id=loicgreffier_docsource\u0026metric=coverage\u0026view=list)\n[![SonarCloud Tests](https://img.shields.io/sonar/tests/loicgreffier_docsource/main?server=https%3A%2F%2Fsonarcloud.io\u0026style=for-the-badge\u0026logo=sonarcloud)](https://sonarcloud.io/component_measures?metric=tests\u0026view=list\u0026id=loicgreffier_docsource)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?logo=apache\u0026style=for-the-badge)](https://opensource.org/licenses/Apache-2.0)\n\n[Download](https://github.com/loicgreffier/docsource/releases) • [Getting Started](#getting-started)\n\nCommand-line interface for detecting broken links in Markdown documentation files.\n\n![](.readme/demo.gif)\n\n\u003c/div\u003e\n\n## Table of Contents\n\n* [Download](#download)\n* [Getting Started](#getting-started)\n    * [Supported Frameworks](#supported-frameworks)\n    * [Links](#links)\n        * [External Links](#external-links)\n        * [Relative Links](#relative-links)\n        * [Mailto Links](#mailto-links)\n* [Usage](#usage)\n    * [Scan](#scan)\n        * [All Absolute](#all-absolute---all-absolute)\n        * [Content Directory](#content-directory---content-directory)\n        * [Image Directory](#image-directory---image-directory)\n        * [Index Filename](#index-filename---index-filename)\n* [Continuous Integration](#continuous-integration)\n    * [GitLab CI/CD](#gitlab-cicd)\n* [FAQ](#frequently-asked-questions-faq)\n* [Motivation](#motivation)\n\n## Download\n\nYou can download Docsource from the [GitHub releases page](https://github.com/loicgreffier/docsource/releases).\nIt is available in four different formats:\n\n- JAR (requires Java 21)\n- Windows\n- Linux, statically linked with Musl\n- MacOS\n\nAdditionally, Docker images are available on [Docker Hub](https://hub.docker.com/r/loicgreffier/docsource):\n\n- The `docsource:\u003cversion\u003e` images contains Docsource as a native binary.\n- The `docsource:\u003cversion\u003e-jar` images contains Docsource as a JAR.\n\n## Getting Started\n\nDocsource should be run from the root directory of your documentation.\n\n```bash\ndocsource scan --recursive . \n```\n\n### Supported Frameworks\n\nDocsource tries to detect the framework used to generate the documentation and applies the appropriate configuration.\nThe supported and tested frameworks are:\n\n- [Docsify](https://docsify.js.org)\n- [Hugo](https://gohugo.io)\n\n### Links\n\nDocsource can check three types of Markdown links: external links, relative links, and mailto links.\n\n#### External Links\n\nExternal links point to an external domain.\nDocsource sends an HTTP request and check the HTTP return code:\n\n- The link is considered broken if the return code is 404.\n- The link is considered valid if the return code is anything other than 404.\n\n#### Relative Links\n\nRelative links point to the same domain.\nDocsource checks if the linked resource actually exists:\n\n- The link is considered broken if the linked resource does not exist.\n- The link is considered valid if the linked resource exists.\n\nA relative link can be either absolute or relative:\n\n- Absolute links are checked from the current user directory (i.e., the root directory of the documentation)\n  concatenated with the content directory if provided (`--content-directory`) or the image directory for images if\n  provided (`--image-directory`).\n- Relative links are checked from the file the link belongs to.\n\n#### Mailto Links\n\nMailto links point to an email address.\nDocsource checks the format of the email address:\n\n- The link is considered broken if the format is incorrect.\n- The link is considered valid if the format is correct.\n\n## Usage\n\n### Scan\n\n```console\n  ____\n (|   \\\n  |    | __   __   ,   __          ,_    __   _\n _|    |/  \\_/    / \\_/  \\_|   |  /  |  /    |/\n(/\\___/ \\__/ \\___/ \\/ \\__/  \\_/|_/   |_/\\___/|__/\n\nUsage: docsource scan [-AhIkrvV] [--skip-external] [--skip-mailto] [--skip-relative] [--content-directory=\u003ccontentDirectory\u003e]\n                [--image-directory=\u003cimageDirectory\u003e] [--index-filename=\u003cindexFilename\u003e] [files...]\n\nDescription:\n\nScan documentation.\n\nParameters:\n      [files...]         Root directories or files to scan.\n\nOptions:\n  -A, --all-absolute     Consider relative paths as absolute paths.\n      --content-directory=\u003ccontentDirectory\u003e\n                         Specify a sub-directory of the root directory containing the Markdown files. E.g., 'content' for Hugo.\n  -h, --help             Show this help message and exit.\n  -I, --image-absolute   Consider relative image paths as absolute paths.\n      --image-directory=\u003cimageDirectory\u003e\n                         Specify a sub-directory of the root directory containing the images. E.g., 'static' for Hugo.\n      --index-filename=\u003cindexFilename\u003e\n                         Specify the filename to use as an index file. E.g., '_index.md' for Hugo.\n  -k, --insecure         Turn off hostname and certificate chain verification.\n  -r, --recursive        Scan directories recursively.\n      --skip-external    Skip external links.\n      --skip-mailto      Skip mailto links.\n      --skip-relative    Skip relative links.\n  -v, --verbose          Enable the verbose mode.\n  -V, --version          Print version information and exit.\n```\n\n`Scan` is used to scan Markdown files in your documentation to detect broken links.\nThe command should be run from the root folder of your documentation.\n\n#### All Absolute (`--all-absolute`)\n\nIf you need to check relative link paths as absolute paths rather than from the file the link belongs to, you can use\nthe `--all-absolute` option.\n\n#### Content Directory (`--content-directory`)\n\nIf the documentation is located in a subdirectory of the root directory, you can specify the content directory using\nthe `--content-directory` option.\n\nE.g., for Hugo, the content directory is `content`.\n\n#### Image Directory (`--image-directory`)\n\nIf the images are located in a subdirectory of the root directory, you can specify the image directory using the\n`--image-directory` option.\n\nE.g., for Hugo, the image directory is `static`.\n\n#### Index Filename (`--index-filename`)\n\nIf the documentation uses a specific filename as an index file, you can specify the index filename using the\n`--index-filename` option.\n\nE.g., for Hugo, the index filename is `_index.md`.\n\n## Continuous Integration\n\n### GitLab CI/CD\n\nDocsource can be run in a GitLab pipeline using the [Docker image](https://hub.docker.com/r/loicgreffier/docsource).\n\n```yaml\ncheck links:\n  stage: verify 🩺\n  image: loicgreffier/docsource\n  script:\n    - docsource scan --recursive .\n```\n\n## Frequently Asked Questions (FAQ)\n\n[How can Docsource trust my SSL certificates](#how-can-docsource-trust-my-ssl-certificates)\n\n### How can Docsource trust my SSL certificates\n\nYou can make Docsource trust your SSL certificates if you need it.\n\nIf you use the JAR, add your SSL certificates in the JVM cacerts.\n\nIf you use the native executables, you can load a trust store dynamically at runtime\nas [specified by GraalVM](https://www.graalvm.org/22.1/reference-manual/native-image/CertificateManagement/).\n\n```console\ndocsource scan . -Djavax.net.ssl.trustStore=pathToTheTrustStore -Djavax.net.ssl.trustStorePassword=trustStorePassword\n```\n\n## Motivation\n\nMaintaining documentation with tens or hundreds of pages can be a pain, and there's nothing more frustrating for readers\nthan encountering broken links. Docsource helps keep documentation up-to-date and detects broken links.\n\nIt was also an opportunity to test\nout [Spring Native](https://docs.spring.io/spring-native/docs/current/reference/htmlsingle/)!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floicgreffier%2Fdocsource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floicgreffier%2Fdocsource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floicgreffier%2Fdocsource/lists"}