Contributing

Hi! 👋 We’re excited that you’re interested in contributing! Take a moment to read the following guidelines. And thanks for contributing to MDX! 👏👌✨

If you’re raising an issue, please understand that people involved with this project often do so for fun, next to their day job; you are not entitled to free customer service.

Questions
Contributions
Running the tests
Submitting an issue
Submitting a pull request
Project structure
Releases
Troubleshooting
Resources

Questions

Please chat and ask questions on spectrum! Jump in there and lurk, talk to us, and help others.

Contributions

There’s several ways to contribute, not just by writing code.

It’s possible to support us financially by becoming a backer or sponsor of unified through Open Collective. With this support, we can pay for project leadership, finance non-coding work, or to do fun things for the community like getting stickers for contributors. You’ll be helping unified’s maintainers manage and improve existing projects, and additionally support our work to develop new and exciting projects, such as micromark.

Improve documentation

As a user of this project you’re perfect for helping us improve our docs. Typo corrections, error fixes, better explanations, new examples, etcetera. Anything!

Improve issues

Some issues lack information, aren’t reproducible, or are just incorrect. Help make them easier to resolve.

Give feedback on issues and pull requests

We’re always looking for more opinions on discussions in the issue tracker.

Write code

Code contributions are very welcome. It’s often good to first create an issue to report a bug or suggest a new feature before creating a pull request to prevent you from doing unnecessary work.

Running the tests

yarn
yarn bootstrap
yarn test

Tests for an individual package can be run as a yarn workspace: yarn workspace remark-mdx test. To see what packages ar available to test you can list out all workspaces with yarn workspaces info.

Submitting an issue

The issue tracker is for issues. Use chat for support
Search the issue tracker (including closed issues) before opening a new issue
Ensure you’re using the latest version of our packages
Use a clear and descriptive title
Include as much information as possible: steps to reproduce the issue, error message, version, operating system, etcetera
The more time you put into an issue, the better we will be able to help you
The best issue report is a failing test proving it

Submitting a pull request

Non-trivial changes are often best discussed in an issue first, to prevent you from doing unnecessary work
For ambitious tasks, you should try to get your work in front of the community for feedback as soon as possible
New features should be accompanied with tests and documentation
Don’t include unrelated changes
Test before submitting code by running yarn test
Write a convincing description of why we should land your pull request: it’s your job to convince us

Project structure

MDX is a monorepo that uses lerna.

All packages are found in ./packages
All documentation is found in ./docs and can be viewed with yarn docs -- -o
There’s an ./examples directory where examples for different tools and frameworks

Releases

In order to release a new version you can follow these steps:

Draft a release for the next version (vX.X.X)
Release a prerelease
- yarn lerna publish
- Select prepatch/preminor/premajor
- Sanity check in a project or two with the prerelease
yarn lerna publish
Publish release on GitHub