This is the repo for the mParticle doc site. You can contribute via submitting issues, or by contributing directly to the codebase itself. Read below to learn how to contribute.
mParticle requires that all contributors outside mParticle fill out mParticle's Contributor License Agreement (CLA). Before we accept your pull request, you will need to submit a completed CLA. If this is your first PR, a bot will comment sending you to the CLA to sign. The mParticle CLA is available for review here. You will not be asked to re-sign the CLA unless we revise our CLA.
The repository maintains two primary branches: master and development:
- All changes must be reviewed via a pull request into the
developmentbranch - Once per hour during business hours, our build process will merge the
developmentbranch intomasterand release the site.
Warning: Any changes merged into development will be released!!!
Please be sure to check our existing issues before submitting a new issue so that we don't have duplicate content requests. As always, please adhere to our Code of Conduct when commenting or creating issues.
- Don't submit issues for small typos - try to fix them yourself using the guidelines in this README :)
- Elaborate as much as possible about the changes that you'd like to see. If possible, specify the original copy itself when creating an issue.
There are 2 ways you can commit code:
- Github UI - recommended for small changes
- Develop Locally - recommended for large changes
The site is written in Markdown, all of which is located in the /src/pages directory. The URLs of the site follow the same structure as within the /src/pages directory. To find the Markdown that you'd like to edit, click on the "Edit this Page" on the top right corner of the page you want to edit.
When writing the docs please keep in mind a few basic guidelines:
- We use a lot of unique terms here at mParticle. Integration, Kit, Connection, Input, Output, Platform, App, Site, SDK, server API, etc. Try to be consistent with how these terms are used throughout the scope of an article, and throughout the site.
- Use heading levels to organize content cleanly
- Use Markdown language features such as
preformatted code blocks,<aside>, bullets, numbered lists, bold, and italic to make the article more readable. - The Markdown of the pages itself is a great way to learn by example. If you see a feature/formatting you'd like to replicate, just find the markdown for that page and replicate it.
Click on the "Edit this Page" link at the TOP RIGHT of each editable page. This will bring you to the markdown file for you to make a change. You can preview your changes in Github's markdown viewer, although this will not match identically the formatting of our page. This is generally fine for small updates.
The site uses the Gatsby static site generator. For larger changes it's very useful to run the site locally to preview and iterate on your edits:
- Install Node v6 later and npm
- Fork this repo, then clone your forked repo either from a terminal or the Git-enabled app of your choice, such as Github's own app.
- Create a "feature" branch off of the
developmentbranch. - At a terminal, within the top-level repo directory
npm install
As of January 2022, a dependency of Gatsby may cause your
npm installcommand to fail due to an incompatibility with libvips. As a workaround, you can manually install libvips via brew:brew install vips
For more information, see a discussion on Gatsby's GitHub page.
- Still at a terminal:
npm run develop
- Navigate to
0.0.0.0:8000in a web browser. As you make changes, the docsite will be rebuilt and hotloaded automatically. - (optional) You can build the actual static site with
npm run build.
After your PR gets approved, you should squash and merge your PR. Squashing and merging keeps the commit log clean.
- Check out the
developmentbranch on your computer and thenpullthe latest changes. - Create a branch for your changes off of
development, such asfeature/update-foo - Follow the steps above for building locally.
- Open the markdown file that you'd like to edit in your favorite simple text editor.
- Make your edits. The server running at
0.0.0.0:8000will reload with your changes. - Create a new commit for the updated files, either using Git from the command line, or your favorite Git-enabled app.
- Push your changes to a "feature" branch, and submit a pull request. @mParticle/docs-admin will automatically be added as a reviewer.
- You may be prompted to sign our CLA. Do so and then comment
@cla-bot checkto confirm you've signed. - Once your PR is approved and merged into development, your changes will be automatically merged to development and released within an hour (during weekdays).
To make it easy to go through comments on a doc pull request, we recommend using these tags before the text of each comment:
typo: Correcting a typo nitpick: Not a showstopper, but recommend making the change if possible. For example, changing "will deliver" to "delivers" or changing case on a title. suggestion: Suggestions for additions, or rearranging content or other actions that make the content easier to understand. question: If the reviewer isn't sure whether something is correct or needs to be changed. praise: Comments that praise the change in question and aren't recommending any change.
This project implements some custom markdown tags for html rendering
Simple add the following markdown code in your .md file to generate a series of tabs in your generated pages:
<tabs>
<tab label='Tab 1' group='my-group'>
This is a test tab
</tab>
<tab label='Tab 2' group='my-group'>
This is a second tab
</tab>
<tab label='Tab 3' group='my-group'>
This is the third tab
</tab>
</tabs>This will generate the proper html and css to render tabs in your pages, and provide the proper click/toggle functionality.
The tabs support any custom markdown within the <tab></tab> tags. The html generated will create the tabs and control the toggling functionality.
Please make sure that you provide a group for your collection as this may break the click/toggle functionality
