Deadlink-Hunter-Website🕵️

Prefer a different language?

This README is available in multiple languages. Click below to switch:

• 🇨🇳 简体中文 (Simplified Chinese)
• 🇧🇷 Português Brasileiro

Deadlink-Hunter is an open-source project designed to find broken links in GitHub repositories (with future support for other platforms). The goal is to help maintainers keep their documentation clean, reliable, and frustration-free for readers.

Deadlink Hunter Website is the frontend of the website.

You can also check Broken-Link-Checker, this is the backend of the project that checks if a link is broken or not. Additionally, check out Deadlink-Crawler, a new repository for crawling and analyzing links efficiently.

The project was inspired as a way to give back to the open source community, everyone is welcome.

This is the general design desired for the website, generated by Lovable, just to provide inspiration.

You can see the deployed website here: Deadlink-Hunter Website

You can check the more elaborated ui that was created with base44 as initial inspiration.

Back to the top of page

---

⚠️ Important Prerequisites

Please Note: This repository contains the Frontend (User Interface) of the Deadlink-Hunter project.

To fully use the scanner features, you MUST run the Backend server locally (or connect to a deployed instance). The frontend communicates with the backend to perform the actual link checking.

Get the Backend here: Broken-Link-Checker Repository

---

Table of Contents

• The why
• Contributing
• Contributors
• Docker Setup
• Mantine Vite template
• Features
• pnpm scripts
• Build and dev scripts
  • Testing scripts
  • Other scripts

Go back to the top of page

The Why

Documentation is the first entry point for most developers exploring a project. Yet, README files and docs often contain outdated or broken links – even in large, well-maintained repositories.

But aren’t there already broken link checkers? There are — but most of them don’t look very good, their UIs are not user-friendly, and their broken link detection doesn’t cover all cases (for example, localhost:4000 is not actually broken).

Go back to the top of the page

Contributing

Contributions are welcome and greatly appreciated!

To contribute:

1. Fork this repository to your own GitHub account.

2. Clone your fork locally:

   git clone https://github.com/<your-username>/Broken-Link-Website.git
   cd Broken-Link-Website
   

3. (Optional) Install pnpm package manager from this link.

4. Install dependencies using pnpm (please do not use npm or yarn):

   pnpm install

5. Run this project:

   pnpm run dev

6. Create a new branch for your feature or fix:

   git checkout -b my-feature

7. Make your changes and commit them with clear messages.

8. Push your branch to your fork:

   git push origin my-feature

9. Create a Pull Request from your repository’s branch to the main branch of the original repository.

⚠️ Heads up: PRs that are fully AI generated and not checked by a human won’t be accepted.

Go back to the top of the page

Environment Variables

This project includes a .env.example file in the repository that lists the environment variables required to run the app.

Before running the project, create a local .env file based on the example. You can copy it quickly using the command below:

# macOS / Linux
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Configure Backend Connection

The .env file includes the variable:

• VITE_API_BASE_URL — the base URL for the backend API.
  Default: http://localhost:3000

Ensure your backend server is running on this port, or update the value to match your backend configuration.

Docker Setup

This project includes Docker support for easy deployment and development. You can run the application using Docker in two ways:

Option 1: Using Docker Compose (Recommended)

The easiest way to run the application is using Docker Compose:

# Build and start the application
docker-compose up --build

# Or run in detached mode (background)
docker-compose up --build -d

The application will be available at http://localhost

To stop the application:

docker-compose down

Option 2: Using Docker directly

You can also build and run the Docker container directly:

# Build the Docker image
docker build -t deadlink-hunter .

# Run the container
docker run -p 80:6006 deadlink-hunter

The application will be available at http://localhost

Docker Configuration

• Port: The application runs on port 6006 inside the container and is mapped to port 80 on your host machine
• Web Server: Uses nginx to serve the built application
• Build Process: Multi-stage build that installs dependencies, builds the app, and serves it with nginx
• Base Image: Built on node:20-alpine for the build stage and nginx:1.27-alpine for the runtime

Go back to the top of the page

API & Postman Collection

The backend exposes a REST API for checking broken links.

We generated a Postman collection based on the internal Swagger documentation to help you test the API locally.

🔗 How to Use the Postman Collection

1. Open Postman

2. Click Import

3. Select File and upload:

   ./postman/broken-link-checker.postman_collection.json

Click here to download the file directly

Make sure your backend server is running at http://localhost:3000 (or adjust the base URL in Postman if needed).

Mantine Vite template

This project is based on the Mantine Vite template.

Go back to the top of the page

## Features

This template comes with the following features:

• PostCSS with mantine-postcss-preset
• TypeScript
• Storybook
• Vitest setup with React Testing Library
• ESLint setup with eslint-config-mantine

Go back to the top of the page

pnpm scripts

Go back to the top of the page

## Build and dev scripts

• dev – start development server
• build – build production version of the app
• preview – locally preview production build

Testing scripts

• typecheck – checks TypeScript types
• lint – runs ESLint
• prettier:check – checks files with Prettier
• vitest – runs vitest tests
• vitest:watch – starts vitest watch
• test – runs vitest, prettier:check, lint and typecheck scripts

Other scripts

• storybook – starts storybook dev server
• storybook:build – build production storybook bundle to storybook-static
• prettier:write – formats all files with Prettier

Go back to the top of the page

Contributors

Thanks to all the amazing contributors who have helped make this project better! 🎉

Go back to the top of the page