-
Notifications
You must be signed in to change notification settings - Fork 68
Home
This is repo for the Amplitude Developer Docs
We use Material for MkDocs to create our docs.
If you have any questions, comments, or concerns open an issue.
Anyone can suggest changes to the docs. Just open a PR with your changes! See our contribution guide to get started.
Install Material with 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
We use markdown-link-check to check for broken links. Megalinter picks up broken links when you open a PR, and you must fix them before merging, so it's best to catch them locally first.
You have a couple of options for installing it, so check out the markdown-link-check docs for instructions.
After you've installed it, you have two options for checking a file locally:
- Run
markdown-link-check -c .markdown-link-check.json path/to/file - Use the
linkcheck.shscript included in the repo:bash linkcheck.sh path/to/file
Both of these commands do the same thing.
Vale is a style linter we use to help enforce consistency and accessibility 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 the docs are.
vscode-drawio is a VS Code plugin that enables you to create and edit diagrams in VS Code without saving and pasting png files created by other diagramming applications like Lucidchart so that you don't need to store a local png and an editable version and manage the two separately. Even better you can save your diagram, refresh the local server and see the updated image.
- Install vscode-drawio to your VS Code.
- Create a digram with suffix
.drawio.svg. Or you can see existing an existing example
-
Ampliteers: Clone the repo:
git clone https://github.com/Amplitude-Developer-Docs/amplitude-dev-center.git. If you aren't on the team, request access in the #dev-doc-requests channel. Note that this repo is PUBLIC and opening a pull request makes your content PUBLIC. If you are working on a secret feature, reach out in the #dev-doc-requests channel. - Everyone else: Fork the repo.
See our formatting cheatsheet for help with our most frequently used formatting elements.
Preview changes locally using mkdocs serve
When you're ready, open a PR against main. Fill out the pull request template the best you can.
📌 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. You will see them on the preview site when you open a PR.
Merge. After your PR is approved, you can merge it if you have write access. If you don't, then someone on the team will merge for you. Merging to main publishes to the website.
-
Three 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. There is a third config fileinsiders.local.build.ymlwhich is identical toinsiders.mkdocs.yml, but disables the plugins that slow down builds significantly, such as privacy and glightbox. None of this should affect casual contributors who don't use Insiders locally. -
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 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.