Skip to main content

Contributing

Thanks for trying to contribute or interesting.

You can contribute to:

Its purpose is all developers are able to better markup and fit each of diverse their projects. So we want you to contribute. Your thought leads to diversity.

Before you open a pull request​

Pull requests that do not meet the conditions below may be closed without review. Opening many pull requests across many repositories in a short time is treated as spam, and those pull requests are closed regardless of their content.

Which issues accept a pull request​

Open a pull request only for an issue that has the Pull Request Wanted label.

Other issues are usually being worked on by a maintainer already, and a pull request for them duplicates that work. If there is no issue for your change, open one first. The only exception is a change that does not alter behavior, such as a typo fix.

What the pull request body must contain​

  1. The issue — Fixes #N. For a change with no issue (the typo-fix exception above), say that the change does not alter behavior.
  2. The cause — why the problem happened, in your own words. A description of what the diff changes is not a cause.
  3. Verification — how you reproduced the problem before the change, and which tests you ran after it.
  4. AI assistance — whether you used AI tools; if you did, what you used them for (code, tests, the description) and what review you had them do on the change. Write "None" if you did not.

Using AI tools​

You may use AI tools. You are responsible for the change all the same: you must understand every line of it and be able to answer review questions in your own words. A pull request whose author cannot explain the change will be closed.

Code contribution​

You need:

  • Node.js v24 or later (the exact version is pinned in .mise.toml; install mise and run mise install to match it)
  • Yarn 4.x (pinned in both .mise.toml and package.json#packageManager — bump them together; CI derives the sandbox Yarn version from the latter)

After cloning this repository, you can also install them through Docker.

When you wrote code then:

  • Format and lint code through yarn lint.
  • Check to build successfully through yarn build.
  • Test your code through yarn test (this also runs TypeScript type-checking on spec files).
  • Push to the topic branch and open a pull request against dev (against v6 when the issue has only the v6 label) with the body described in What the pull request body must contain. Reviewers are assigned automatically.

nu-validator compatibility benchmark​

tests/external/ houses a local-only benchmark that compares markuplint with Nu Html Checker. It is not wired into CI. See tests/external/CLAUDE.md for the setup, command list, and the Docker / excluded-ids.json workflow.

Publishing the VS Code Extension​

The npm packages are published automatically from CI (npm trusted publisher). The VS Code extension, in contrast, is published manually after the core packages land. See vscode/CLAUDE.md for why stable and prerelease versions are distributed through different channels.

Publisher​

The extension is published under the markuplint publisher (Marketplace ID: markuplint.markuplint-vscode).

The legacy yusukehirao.vscode-markuplint listing was deleted from the Marketplace at the v5.0.0 release (see vscode/CLAUDE.md for why it could not simply be left deprecated).

yarn vscode:login runs vsce login markuplint, so the Azure DevOps Personal Access Token you authenticate with must have rights on the markuplint publisher.

Versioning​

All packages — including the VS Code extension — share a single version because Lerna is configured in non-independent mode. The extension version always matches the core version (e.g. 5.0.0, 5.0.0-rc.4).

Workflow​

Only stable versions (X.Y.Z without a prerelease suffix) are published to the Marketplace.

  1. Wait for the core packages to be published to npm by CI
  2. Pull the release tag locally (git pull --tags)
  3. (First time only) yarn vscode:login to authenticate with Marketplace
  4. Run yarn vscode:release

yarn vscode:package produces a local .vsix without publishing — use it for smoke-testing before running the publish command.

Valid modes accepted by vscode/scripts/install.mjs: package, release.

Reference​