This is the Amplitude Developer Center site. This site is currently in beta and the workflows may change.
Anyone can suggest changes to our docs. Just open a PR with your changes!
- To get started with contributing, check out the Developer Docs Confluence site. There, you'll find more conceptual content, including style guides and markdown cheatsheets.
- If you're working on a feature that hasn't been announced yet, do your work in the amp-internal-dev repo. When you're ready to ship, open a PR against main. Learn more in Confluence.
Before you get started, you need pip. To install the link checker and Vale locally, you need brew and npm too.
This command installs almost every dependency.
pip install mkdocs-material
pip install mkdocs-git-revision-date-plugin
NOTE: This currently isn't working. Check back later. Waiting on the author to make fixes.
npm install -g markdown-link-check
We use a GitHub Action that runs a link checker for PRs, but it's annoying to only find out links are broken after you open your PR. If you install the link checker, run the linter locally with this command: markdown-link-check -c .github/workflows/link-check-config.json path/to/your/file.md. It's not perfect, so if you find that the job repeatedly fails on a valid link, then add the pattern to ignore to the .github/workflows/link-check-config.json file.
Vale is a style linter we use to help enforce consistency and accessibilty in our docs. Our style guide config is included in this repo. To use the linter, you need to install Vale.
brew install vale
After it's installed, you can run Vale in the terminal. See Vale docs. You can also install the plugin for your editor:
The changes Vale flags are mostly suggestions, but please make an effort to address problems. The closer we stick to the style guide, the better our docs will be.
git clone https://github.com/Amplitude-Developer-Docs/amplitude-dev-center.git
Note for Ampliteers: If you're working on a secret feature, use the amp-internal-dev repo instead. Contact Casey Smith for access and instructions.
Preview changes locally using mkdocs serve
When you're ready, open a PR against the staging branch*.
Note for Ampliteers: *If you have questions about which staging branch to use, ask in #dev-doc-requests.
After your PR is approved, we'll merge it. Merging to main publishes to the website.
- The files in the repo make use of Insiders features. If you don't have Insiders, you can still build, but some features won't render in your build. However, you can see them on the preview site when you open a PR.
- If you're using VS Code, install the markdownlint extension. This extension flags problems with your markdown. The project includes a config file to cut down on noisier errors.
- Two mkdocs config files. Because of the way Insiders and config inheritance work, I had to make a config file for people who don't have Insiders and one for the build bot (which does have Insiders). This was intentional. Site builds should always use
insiders.mkdocs.yml. If you want to know more, read the dissertation I wrote ininsiders.mkdocs.yml. - Column CSS classes. Markdown tables are easier to write than HTML tables. However, column width is set by the width of the contents in the first cell for each column. This can lead to too-narrow column widths in some data tables (especially param tables). Because you can add HTML to markdown, I created some CSS classes to manually set the width in cases where it makes sense. Just wrap the contents of the column's table heading with a
<div class="big-column">(180px) or(100px) as needed. Seedocs/stylesheets/extra.cssand search for "column width classes" for an explanation and the classes. - Unsupported language syntax highlighting. The project uses Pygments for code syntax highlighting. As with all highlighters, some languages aren't explicitly supported. If you can't find your language supported in this list, you can either write your own, or just use the closest thing you can. This is an edge case. For NodeJs, just use
js.