If you'd like to contribute to Astronomer docs directly, you are welcome to create a Pull Request (PR) to this repository with your suggested changes. To do so:
- Clone this repository
- Create a branch off of
main - Make your changes in that branch
- Submit a PR for review
Once you have submitted a PR for your changes, Netlify will add a comment to your PR that includes a link to a staging website with your changes.
Small edits and typo fixes don't need to be linked to an issue and should be merged quickly. To get a timely review on a larger contribution, we recommend first creating a GitHub issue describing the problem and linking that within your PR.
Every update to the main branch of this repository will trigger a rebuild of our production documentation page at https://www.astronomer.io/docs. It might take a few moments for your merged changes to appear.
For more detailed instructions and workflows when contributing to docs as an Astronomer team member, see the Astronomer Docs Contribution Notion, Astronomer Doc Types Overview, and Astronomer Docs Spec.
There are 3 core documentation folders in this repository:
astrosoftwarelearn
These folders contain the primary Astronomer docsets that you see by default on Astronomer's documentation site. Docs for the Astro CLI live within the astro folder.
The software directory is equivalent to the Latest version of the Astronomer Software docset, which is the docset that users see by default when accesssing www.astronomer.io/docs/software. An additional software_versioned_docs folder contains docsets for previous versions of Software. Whenever there's a new release of Astronomer Software, a new versioned docset is copied from software and added to this folder, with all links and sidebars updated automatically by Docusuaurs.
If you're working on a change in Software docs, you should work primarily in software. Make changes to software_versioned_docs only if your change is version-specific or a critical fix (e.g. incorrect or out-of-date information).
If you want to contribute new docs to the Astro, Software, or Astro CLI docs, you can get started by copying one of the standard Doc templates when you make your initial PR. These templates include links to examples of similar docs as well as guiding questions that your new content should answer.
There are four standard templates:
- Overview - Gives a detailed explanation about what something is, how it functions as a part of Astronomer products or in an implementation, and why someone should use it. All docs should have at least one sentence explaining why a feature is important to a user.
- Decision - Provides a summary of available implementation options, explains the benefits and trade-offs of each, shares recommended and best practices, and makes recommendations for pairing implementation options with use cases.
- Process - Docs that share a series of actions to complete an objective. They should be introduced with a short paragraph about what the end state of the procedure is and why someone should complete it.
- CLI Reference - The Astro CLI command reference docs are highly structured to ensure the docs adequately answer the question “What is it?” and provide definitions, defaults, examples, and explanations of what a feature, term, or concept is.
Pick the template that best fits the type of content you want to make, make a copy, and replace the template content with your own information that addresses the questions the template prompt you to answer.
For Astronomer team members, you can find additional information about the Doc Templates and standards in our internal documentation. See Astronomer Doc Types Overview, and Astronomer Docs Spec.
If you want to submit a change to the Astronomer docs site itself, or test a screenshot, GIF, or a new documentation file, you may want to build and test your documentation change locally. Astronomer docs are built with Docusaurus, which is an open-source documentation framework and our static site generator. The Astronomer docs site is built on Netlify. Read the following sections for instructions on how to build and test your documentation changes locally with Docusaurus and Yarn.
To build docs locally, you need to install both Node and Yarn. While Yarn is included in Node, starting in 2020, the Yarn binaries are bundled within Corepack. If you're installing Node for the first time, you need to manually enable Corepacks before you can use Yarn.
-
Follow the instructions on Nodejs to install Node, then confirm that you successfully installed Node by running the following command:
node -version
-
Run the following command to enable
corepacksand make Yarn available:corepack enable
After you install Node and enable Yarn with Corepacks, Docusaurus commands are available when you open the docs directory from your terminal.
Please read the Docusaurus documentation for information on installing other tools you'll need to work with Docusaurus locally.
If you used an alternative package manager to install Node, such as npm or homebrew, you might need to troubleshoot your install.
-
Run the following command to check your Node version:
node --version
-
Adjust your installation based on the output of the command:
- Node and yarn are installed, but need to be updated: Use a package manager like npm or nvm to update your version, or download the installer from the Node.js site.
- Node is installed, but you cannot enable Corepack: If you installed Node using a package manager, and it's above version 16.10, but Corepack isn't available, follow the instructions for installing Corepack with npm or installing Corepack with Homebrew or nvm, then run the following command to enable Corepack:
corepack enable
To serve a local version of the docs site with your changes, run:
yarn run startYou might also need to install fs-extra before you can build the site locally. To install it, run:
yarn add fs-extraThis command both builds and serves your local changes. By default, your local build is accessible at localhost:3000. From here, any changes you save in your text editor will render on this local site in real time.