Skip to main content
This guide will help you set up your development environment for contributing to Linkspector. Follow these instructions to ensure you have all the necessary tools and dependencies installed.

​
Prerequisites

Before you begin, make sure you have the following prerequisites installed on your system:

​
Node.js

This project requires Node.js, a JavaScript runtime, to build and run. You can download and install Node.js from the official website: Node.js Download. To check if Node.js is installed, open your terminal and run: 
node -v
You should see the installed Node.js version (e.g., v18.0.0 or higher).
Linkspector requires Node.js version 14 or higher. We recommend using the latest LTS (Long Term Support) version.

​
Git

You’ll need Git to clone the repository and manage version control. Most systems have Git pre-installed, but you can download it from git-scm.com if needed. To verify Git is installed: 
git --version

​
Installation

After ensuring you have the prerequisites installed, follow these steps to set up your development environment:
1

Fork and clone the repository

First, fork the repository on GitHub, then clone it to your local machine:
git clone [email protected]:YOUR_USERNAME/linkspector.git
Replace YOUR_USERNAME with your GitHub username.
2

Navigate to the project directory

Change into the project directory:
cd linkspector
3

Install dependencies

Use npm to install all project dependencies:
npm install
This command will download and install all the required packages specified in the package.json file.
4

Verify the installation

Run the tool locally to verify everything is set up correctly:
./index.js --help
You should see the Linkspector help message with available commands.

​
Running Linkspector Locally

Once you’ve completed the setup, you can run Linkspector locally for testing and development.

​
Basic Usage

To run Linkspector on the project itself: 
./index.js check

​
Using a Custom Configuration

To test with a custom configuration file: 
./index.js check -c .linkspector.test.yml

​
JSON Output

To see the JSON output format (useful for testing integrations): 
./index.js check -j
The JSON output follows the rdjson format used by reviewdog.

​
Running Tests

Linkspector uses Vitest as its test framework. To run the test suite:

​
Run All Tests

npm test
This command runs all tests once with a 60-second timeout for each test.

​
Watch Mode

For continuous testing during development: 
npm run test:watch
This will run tests automatically whenever you make changes to the code.

​
Code Formatting

To check code formatting: 
npm run prettier:check
To automatically format code: 
npm run prettier:format

​
Project Structure

Understanding the project structure will help you navigate the codebase and make meaningful contributions: 
linkspector/
├── index.js                 # CLI entry point
├── linkspector.js          # Main application logic
├── lib/                    # Core functionality modules
│   ├── batch-check-links.js
│   ├── check-file-links.js
│   ├── extract-asciidoc-comprehensive.js
│   ├── extract-asciidoc-links.js
│   ├── extract-markdown-hyperlinks.js
│   ├── get-unique-links.js
│   ├── handle-links-modification.js
│   ├── prepare-file-list.js
│   ├── update-linkstatus-obj.js
│   ├── validate-asciidoc-references.js
│   ├── validate-config.js
│   └── validate-rdjson.js
├── test/                   # Test files
├── .github/                # GitHub Actions workflows
├── package.json            # Project dependencies and scripts
└── vite.config.ts         # Vitest configuration

​
Key Files

  • index.js: The CLI entry point that handles command-line arguments using the Commander library
  • linkspector.js: Contains the main application logic for link checking
  • lib/: Directory containing modular functionality:
    • Link extraction for different formats (Markdown, AsciiDoc)
    • Link validation and checking
    • Configuration validation
    • Reference validation
When adding new features, consider whether they belong in an existing module or require a new module in the lib/ directory.

​
Development Workflow

Here’s a typical development workflow:
1

Create a feature branch

Always create a new branch for your changes:
git checkout -b feature/your-feature-name
2

Make your changes

Edit the relevant files and add your improvements.
3

Test your changes

Run the test suite to ensure nothing is broken:
npm test
4

Run the tool locally

Test your changes by running Linkspector on sample files:
./index.js check
5

Format your code

Ensure your code follows the project’s formatting standards:
npm run prettier:format
6

Commit your changes

Commit with a clear message following the commit message guidelines:
git add .
git commit -m "Add support for new feature"
7

Push and create a PR

Push your changes and create a pull request:
git push origin feature/your-feature-name

​
Using Docker for Development

You can also develop and test Linkspector using Docker:
1

Build the Docker image

From the project root, build the Docker image:
docker build --no-cache --pull --build-arg LINKSPECTOR_PACKAGE= -t umbrelladocs/linkspector .
2

Run Linkspector in Docker

Test your changes in the Docker container:
docker run --rm -it -v $PWD:/app \
       --name linkspector umbrelladocs/linkspector \
       bash -c 'linkspector check'

​
Troubleshooting

​
Common Issues

Dependencies not installing
  • Try deleting node_modules and package-lock.json, then run npm install again
  • Ensure you’re using a compatible Node.js version (14+)
Tests failing
  • Make sure all dependencies are installed: npm install
  • Check if there are any environment-specific issues
  • Review the test output for specific error messages
Puppeteer issues
  • Linkspector uses Puppeteer for link checking. On some systems, you may need to install additional dependencies
  • See the Puppeteer troubleshooting guide for system-specific requirements
If you encounter issues not covered here, please open an issue on GitHub.

​
Next Steps

Now that you have your development environment set up:
  • Review the Contributing Guidelines to understand the contribution process
  • Check out open issues to find something to work on
  • Read through the codebase to familiarize yourself with the architecture
  • Join the discussions to connect with other contributors
Happy coding!

Build docs developers (and LLMs) love

Get started for freeTalk to us