Link Checks and SEO Optimizations
Hyperlint can check for SEO and link issues in your documentation.
Hyperlint can check every pull request and change to ensure that all of the links in your documentation are valid and that your documentation is optimized for SEO. The link validation and SEO results will be displayed in a GitHub Check on the pull request.
See Configuration for details on how to enable Link Checks and SEO Optimizations.
SEO & Link Checks
We have a variety of supported links:
- External links (for example,
[link to example.com](https://example.com)) - External image links (for example,
) - Internal links (coming soon)
- Anchor links (coming soon)
Link Checking Valid Status Codes
| Code Range | Valid or Invalid | Comments |
|---|---|---|
| 1xx | Invalid / Ignored | |
| 2xx | Valid | |
| 3xx | Invalid | |
| 403 | Valid | Some links require a user to be logged in, but is otherwise assumed valid |
| 4xx (aside from 403) | Invalid | Connection errors for invalid domains will be marked as 404 |
| 5xx | Invalid |
SEO Optimizations
In addition to checking for link problems, Hyperlint can also check for SEO optimizations.
- Check existing filenames and suggested the optimal filename.
- Suggest improved image ALT text for any images in your documentation using a Vision Language Model.
These checks ensure that your documentation is optimized for SEO and can be found across the web.
Filename SEO Optimizations
According to the Google URL Structure Guide, it is recommended to use hyphens (-) rather than underscores (_) in filenames. Using underscores helps users and search engines identify concepts in the URL more easily.
Google and other search engines treat hyphens as word separators, similar to spaces. For example, new-york-apartments in a URL is interpreted as "new york apartments." In contrast, underscores are viewed as word joiners, so new_york_apartments is seen by Google as "newyorkapartments."
In practice, if Hyperlint scans your pull request and finds a filename with underscores such as path_to_file.rst, it may suggest to rename this filename to one that uses dashes such as path-to-file.rst.
Image Alt Text SEO Optimizations
According to Google Search Central:
The most important attribute when it comes to providing more metadata for an image is the alt text (text that describes an image), which also improves accessibility for people who can't see images on web pages, including users who use screen readers or have low-bandwidth connections. When writing alt text, focus on creating useful, information-rich content that uses keywords appropriately and is in context of the content of the page.
Hyperlint can automatically SEO optimize the Image Alt attribute text for your image links via Vision Language LLM Models.
For instance, if you include a screenshot of your product’s architecture diagram along with a markdown image link, such as , Hyperlint will automatically analyze the image and provide SEO-optimized alt text suggestions. For example, it may suggest [Backend System Architecture Diagram](http://your.website.com/architecture.png) as improved alt text. This will improve SEO ranking and website accessibility for people who can't see images on web pages.
Since Hyperlint cannot access content on private forks, the Image Alt Text SEO optimization feature is disabled on private fork pull requests.