Skip to main content

Contributing to remark-kroki-a11y

Thanks for considering a contribution! This plugin is plain JavaScript (no build step) and is tested primarily in Docusaurus.

For complete quality standards and acceptance criteria, see the Definition of Done.

Prerequisites​

  • Node.js >= 20 for development (see .nvmrc; the pre-commit hook enforces this). The published package itself supports Node >= 16.
  • npm or yarn

Local development​

  1. Install dependencies:
npm install
# or
yarn install

  1. Make changes in src/ (the entry point is src/index.js).

  2. Run basic sanity checks:

  • Ensure npm pack or yarn pack succeeds.
  • Optionally run node -c src/index.js to catch syntax errors.

Running BDD tests​

BDD tests are located in the test/ directory. Run them with:

yarn test
# or
npm test

These tests will execute all .feature files and check a11y functionality and rendering.

Manual testing with Docusaurus​

To manually test the plugin in a Docusaurus site, use the example markdown file in test-docusaurus-site/plantuml-examples.md.

This file contains various PlantUML diagram scenarios:

  • Diagram only
  • Source code only (expandable)
  • Diagram + source code
  • Diagram + source code + a11y description/tab

You can copy or import this file into your test Docusaurus site to verify plugin behavior.

See the README for more info on plugin configuration.

Generated documentation files​

copy-docs.sh (run automatically by yarn start and yarn build) copies the canonical docs into the Docusaurus site. The generated copies are git-ignored, so always edit the source file:

Source (edit this)Generated (do not edit)
README.mdtest-docusaurus-site/docs/index.md
CONTRIBUTING.mdtest-docusaurus-site/docs/contributing.md
definition-of-done.mdtest-docusaurus-site/docs/definition-of-done.md
docs/adr/test-docusaurus-site/docs/adr/
docs/img/test-docusaurus-site/docs/img/

See ADR-0007 for the rationale.

Testing in a Docusaurus site​

You can link the plugin into a local Docusaurus project to verify behavior:

# In this repo
npm link
# In your Docusaurus project
npm link remark-kroki-a11y

Test Option B: file dependency​

# In the Docusaurus project package.json
"remark-kroki-a11y": "file:../remark-kroki-a11y"

# Then install
npm install
# or
yarn install

Update the Docusaurus remarkPlugins order so this plugin runs before remark-kroki-plugin (see README for the snippet).

Versioning​

This project follows Semantic Versioning (SemVer):

  • MAJOR version for incompatible API changes
  • MINOR version for new functionality (backwards-compatible)
  • PATCH version for backwards-compatible bug fixes

Conventional Commits​

We use Conventional Commits for commit messages to enable automatic version determination:

feat: add support for Mermaid flowcharts      → bumps MINOR
fix: correct parsing of participant names     → bumps PATCH
feat!: change default output format           → bumps MAJOR (breaking)
docs: update README with new examples         → no version bump

Common prefixes:

  • feat: - New feature (MINOR bump)
  • fix: - Bug fix (PATCH bump)
  • docs: - Documentation only
  • refactor: - Code refactoring without feature changes
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

Add ! after the prefix or include BREAKING CHANGE: in the footer for breaking changes (MAJOR bump).

Automated Versioning (Future)​

For automated version management, consider semantic-release:

npm install --save-dev semantic-release \
  @semantic-release/changelog @semantic-release/git

This analyzes commits following Conventional Commits and automatically:

  • Determines the next version number
  • Generates changelog
  • Publishes to npm
  • Creates GitHub release

Publishing (maintainers)​

Manual Publishing​

  1. Ensure all tests pass: yarn test
  2. Bump version in package.json following semver
  3. Run npm pack to confirm the tarball includes expected files
  4. Publish: npm publish (ensure you are logged in to npm)

Coding style​

  • Keep the codebase compatible with Node 16 and CommonJS.
  • Use plain JS, no build tooling required.
  • Prefer small, isolated functions; add inline comments only where non-obvious.

Definition of Done​

Before submitting a PR, ensure your changes meet the following criteria:

Code Quality​

  • ESLint passes - No linting errors (yarn lint or configured in IDE)
  • Markdownlint passes - Documentation follows markdown best practices
  • Syntax valid - node -c src/index.js succeeds without errors

Build & Runtime​

  • Compiles - yarn build completes without errors
  • Runs correctly - yarn start launches without runtime errors
  • Package works - npm pack or yarn pack succeeds

Testing​

  • BDD tests pass - All tests in yarn test succeed
  • New features have tests - Added BDD scenarios for new functionality
  • No regressions - Existing tests still pass

Documentation​

  • Links work - Docusaurus link checker passes (onBrokenLinks: 'throw' is enabled)
  • README updated - New options or features documented
  • Changelog updated - (if applicable)

Pre-commit Checks​

Git hooks are managed with Husky. The hooks live in .husky/ and are installed automatically by the prepare script when you run yarn install, so no manual setup is needed.

.husky/pre-commit runs, in order:

#CheckBlocking?
1Node.js 20+ is available (switches via nvm when .nvmrc is present)Yes
2No package-lock.json in the repo (we use yarn)No — warning
3yarn.lock present in root and test-docusaurus-site/No — warning
4ESLint (yarn lint:js)No — warning
5Quickmark (yarn lint:md)No — warning
6BDD tests (yarn test)Yes

Only the Node version check and the BDD tests abort a commit; the linters print a warning so you can still commit work in progress. Fix lint warnings before opening a PR — see the Definition of Done.

To skip the hook in an emergency, commit with --no-verify. Use this sparingly and never for code that ends up in a PR.

Issues and PRs​

  • When filing issues, include a minimal code block that reproduces the problem (diagram type, meta flags, expected vs actual).
  • For PRs, describe the change, testing steps, and any new options added.
Single Source of Truth

This page is automatically copied from the repository root CONTRIBUTING.md file. The original file is maintained for GitHub and does not contain Docusaurus-specific markup. Edit the root CONTRIBUTING.md to update this page.