Neoplastic Plasma Medusa

    TypeScript icon, indicating that this package has built-in type declarations

    1.1.2 • Public • Published

    seo-lint: A Robust SEO Linter / Checker for Local HTML Files

    This package offers both a CLI and a library to help you with linting HTML for over 50 common SEO issues.

    This SEO tool was spun out of Elder.js' plugin called seo-check.

    Tester (Library Usage)

    The library exports a Tester method which returns an object with 2 methods: folder and test.

    Recursive Folder Linting: folder

    If you have a folder of .html files you're looking to check for common SEO issues, you just need to specify the folder and seo-lint will recursively check all of the .html files for issues.

    const { Tester } = require('./Tester');
    const tester = Tester({ siteWide: true, host: '' });
    const results = await tester.folder('public'); // relative to process.cwd()

    Raw HTML Linting: test

    If you have a build process that generates HTML, such as a static site generator, and want to lint that html generated for common SEO issues you can do the following:

    const { Tester } = require('./Tester');
    const tester = Tester({ host: '' });
    const results = await tester.test(html, relPermalink);
    // results will be an object with issues by url and sitewide issues.


    $ npm i -g  @nickreese/seo-lint


    seo-lint <dir> [options]


    • -H, --host Set the expected host for internal links. (
    • -v, --version Displays current version
    • -c, --config Set a custom config to specify rules.
    • -w, --write Location to write a report to a JSON file.

    CLI config

    // const { defaultPreferences, rules } = require('@nickreese/seo-lint');
    // available if you want the defaults from the package.
    module.exports = {
      rules: [],
      preferences: {},
      writeLocation: `./report.json`, // if this is set it assumes you want the report written.
      display: ['errors', 'warnings'],

    Advanced Example:

    $ seo-lint public -H -c seo-lint.config.js -w report.json



    These are only checked when Elder.js runs in build mode.

    • [x] check for orphaned pages (no incoming internal links)
    • [x] check for broken internal links.
    • [x] check for duplicate title tags
    • [x] check for duplicate meta descriptions


    • [x] canonical tag exists
    • [x] canonical tag matches request.permalink

    Title Tag

    • [x] Title tag exists
    • [x] Title tag innerText and innerHTML are the same. (no html tags in your title tag)
    • [x] Only one title tag per page
    • [x] Title tag is less than 70 chars
    • [x] Title tag is more than 10 chars
    • [x] Title doesn't include common stopwords.
    • [x] Title tag doesn't have null
    • [x] Title tag doesn't have undefined
    • [x] checks for stop words.

    Meta Description

    • [x] meta description exists
    • [x] only one meta description tag per page
    • [x] Meta description doesn't have null
    • [x] Meta description doesn't have undefined
    • [x] Meta description is longer than 10 chars
    • [x] Meta description is less than than 120 chars
    • [x] Meta description is longer than 300 chars (sometimes things go REALLY wrong and this helps catch it.)
    • [x] Meta description includes at least one the keywords of the title tag.


    • [x] h1 Exists on page
    • [x] only a single h1 per page.
    • [x] h1 has at least one word from your title tag
    • [x] h1 is less than 70 chars
    • [x] h1 is more than than 10 chars
    • [x] H2 or H3 don't exist if an H1 is missing.
    • [x] H2 exists on the page
    • [x] h2 is less than 100 chars
    • [x] h2 is more than than 10 chars
    • [x] At least one of your h2s contains a single word from your title tag.
    • [x] h3 is less than 100 chars
    • [x] h3 is more than than 7 chars
    • [x] h4 is less than 100 chars
    • [x] h4 is more than than 7 chars
    • [x] If no h2s checks for h3s.
    • [x] If no h3s checks for h4s.
    • [x] If no h4s checks for h5s.
    • [x] If no h5s checks for h6s.


    • [x] Checks images for alt tags.


    • [x] Internal links are lowercase
    • [x] Internal links have trailing slash
    • [x] Internal links are not nofollow
    • [x] Notifies if there are more than 50 outbound links on the page.
    • [x] check for trailing index.html
    • [x] internal fully formed links include 'https'


    • [x] Checks for width=device-width, initial-scale=1.0 meta viewport.


    Written by Nick Reese. Initially written to audit Elder Guide.


    • We could add a way to filter out rules based on name.


    This project is licensed under the MIT License - see the LICENSE file for details.




    npm i @nickreese/seo-lint

    DownloadsWeekly Downloads






    Unpacked Size

    48.4 kB

    Total Files


    Last publish


    • nickreese