We welcome any contributions to our documentation repository, dvc.org. Contributions can be updates to the documentation content, or (rare) changes to the JS engine we use to run the website.
In case of a minor change, you can use the Edit on GitHub button to open the source code page. Use the Edit button (pencil icon) to edit the file in-place, and then Commit changes from the bottom of the page.
Do check our Writing a Blog Post guide for more details on how to write and submit a new blog post.
To contribute documentation, these are the relevant locations:
content/docs/): Markdown files. One file — one page of the documentation.
static/img/): Add new images (
.svg, etc.) here. Use them in Markdown files like this:
content/docs/sidebar.json): Edit it to add or change entries in the navigation sidebar.
Merging the appropriate changes to these files into the
main branch is enough
to update the docs and redeploy the website.
Find or open a new issue in the issue tracker to let us know that you are working on this.
Format the source code by following the style guidelines below. We highly recommend setting up a development environment as explained below. Among other things, it can help format the documentation and JS code automatically.
Push the changes to your fork of dvc.org and submit a PR to the upstream repo.
We will review your PR as soon as possible. Thank you for contributing!
We highly recommend running this web app locally to check documentation or blog changes before submitting them, and it's quite necessary when making changes to the website engine itself. Source code and content files need to be properly formatted and linted as well, which is also ensured by the full setup below.
$ npm install -g yarn
Having cloned this project locally, navigate into the directory and install the project dependencies with Yarn:
Launch the server locally with:
$ yarn develop
This will start the server on the default port,
http://localhost:8000/ and navigate to the page in question. This will also
enable the pre-commit Git hook that will be formatting and linting your code and
documentation files automatically.
These Node scripts are specified in the docs repo's
To build the project and run it:
yarn develop- run development server with hot reload.
yarn build- build assets in the
yarn start- run production static server over the
All the tests, formatting, and linters below will be enforced automatically upon submitting PRs.
If you change source code files, run tests:
yarn test- run tests.
We use Prettier to format our source code. Below is a set of wrapper commands for your convenience:
yarn format-check- check all source and content files that they are properly formatted. This script does not fix any found issue, only reports them.
yarn format-all- fix all found problems.
yarn format-staged- same, but only on staged files.
yarn format <file>- run this script
yarn format <file-name>to format a specific file.
We use linters (e.g. ESLint) to check source code style and detect different errors:
yarn lint-ts- lint source code files (
yarn lint-css- lint
Note that you can always use the formatter or linter directly (e.g.
yarn eslint <file>or
yarn prettier --check <file>).
Some environment variables are required to deploy this project to production, others can be used to debug the project. Please check the production system settings to see all the variables that production and deployment system depend on.
Some available variables:
GA_ID– ID of the Google Analytics counter.
ANALYZE- boolean property to run webpack-analyzer.
SENTRY_DSN- Sentry URL for errors tracking.
Some of the following rules are applied automatically by a pre-commit Git hook
that is installed when
yarn runs (see dev env).
No trailing white spaces are allowed.
Text content must be properly formatted at 80 symbols width.
💡 We recommend using Visual Studio Code with the Rewrap plugin for help with this.
dvc <command>, the docs engine will create a link to that command automatically. (No need to use
()explicitly to create them.)
dvc.api, the docs engine will create a link to that API method automatically. (No need to use
()explicitly to create them.)
Markdown: Bullet lists shouldn't be too long (5-7 items max., ideally).
Markdown: The text in each bullet item also shouldn't be too long (3 sentence paragraphs max.) Full sentence bullets should begin with a capital letter and end in period
.. Otherwise, they can be all lower case and have no ending punctuation. Bullets can be separated by an empty line if they contain several paragraphs, but this is discouraged: try to keep items short.
Markdown: Syntax highlighting in fenced code blocks should use the
usageis employed to show the
dvc --helpoutput for each command reference.
dvccan be used to show examples of commands and their output in a terminal session.
dvctableis used for creating colored, bold, or italic table cells. (You can see an example of
dvctablein our "Get Started" section.)
yamlis used to show samples of DVC files, or other YAML contents.
diffis used mainly for examples of
Check out the
.mdsource code of any command reference to get a better idea, for example in this very file.
We try to use a casual and fun tone in our docs. We also avoid authoritative language such as "As you can see, clearly this is what happened, of course" etc. which while good-intentioned, may scare readers off.
We prefer general, human-friendly language rather than exact jargon as long as it's correct. Example: avoid Git jargon such as revision or reference, preferring the more basic terms commit or version.
The command reference contains some of our most technical documents where specialized language is used the most, but even there, we use expandable sections for complex implementation details.
Start by writing the essence in simple terms, and complete it with clarifications, edge cases, or other precisions in a separate iteration.
We use bold text for emphasis, and italics for special terms.
We also use "emoji" symbols sparingly for visibility on certain notes. Mainly:
- 📖 For notes that link to other related documentation
- ⚠️ Important warnings or disclaimers related to advanced DVC usage
- 💡 Useful notes and tips, often related to external tools and integrations
Some other emojis currently in use here and there: ⚡ ✅ 🙏 🐛 ⭐ ⚙️ ℹ️ (among others).