We welcome contributions of any size and contributors of any skill level. As an open source project, we believe in giving back to our contributors. We are happy to help with guidance on PRs, technical writing, and turning any feature idea into a reality.
Tip for new contributors: Take a look at GitHub's Docs for helpful information on working with GitHub.
This document is an active work in progress! But, we hope you'll find some useful information here to get started.
There are lots of ways to contribute to the Astro Docs website!
The Structeezy Docs website is an Astro website. Maintaining it requires not only written content but also maintaining Astro code and addressing a11y, CSS, UI, and UX concerns. We also make our documentation available in several languages, so we need help translating the entire site.
You can also make a huge contribution by getting involved by leaving review comments on PRs, adding ideas in existing GitHub Issues and Discussions!
Every PR, especially translation PRs, needs reviewers! Reviewing PRs and leaving comments, suggestions, or an approving "LGTM!" ("Looks Good To Me!") is a great way to get started on Team Docs, and to learn more about Structeezy.
We encourage you to:
-
File an Issue to let us know of outdated, confusing, or incorrect documentation. You can also let us know of any problems you encounter with the plugin and on the site itself.
-
Start a Discussion if you're not sure that your "issue" rises to the level of bug or incorrect documentation requiring a "fix," but you still want to share ideas and opinions.
-
Make a PR directly for very obvious documentation fixes like typos or broken links.
-
Look at our Existing Issues (especially those labelled
help wantedandgood first issue) for contributions we are actively seeking. -
Review Existing PRs (especially translations!) to help us get our fixes implemented live on the website sooner.
We provide new content and rework existing content in response to GitHub Issues and Discussions.
Submitting an Issue is usually the first step to making a change.
Tip: Existing PRs and Issues need reviewing, triaging, and feedback, too! You can make valuable contributions by commenting, suggesting, testing, researching, brainstorming and generally helping in all areas on GitHub!
- typo fixes (to any language)
- correcting broken links (in any language)
- additions or corrections to a short section on a page
- adding a new or undocumented item in a list with a short description
- noting or removing a deprecated feature
- a bug was found in the plugin
- a particular explanation is confusing (with explanation)
- accessibility (a11y) issues discovered
- missing content
- a request for an example of how to implement a specific feature (e.g. responsive nav bar)
- PRs addressing an existing Issue
- unsolicited PRs to address typos, broken links, and other minor problems
- is this page in the right section of the docs?
- is anything missing from our docs landing page?
- is this theme color too bold?
- is site navigation clear and helpful?
If you're unsure which type of contribution best represents your concern, please make a new issue!
Helpful issues usually include:
- Clear descriptive titles
- Links to relevant pages/files
- Explanations as to why (or for whom) this is a problem
- Optional: proposed solutions
Need help making a PR? Join us on Discord, we'll be more than glad to help you out!
Contributions to the documentation site are made by editing the docs repository. You can do this directly on github.com or by creating a copy of the repository locally, making your changes there, and contributing back to our repository.
Internationalization (i18n)
Please only add new text content to the docs in English, by modifying only .md or .mdx files located within src/content/docs/ but not in locals subfolders like src/content/docs/fr/ or src/content/docs/es/.
Every page on docs.structeezy.com has an Edit this page button in the sidebar. You can click that button to edit the source code for that page in GitHub.
After you make your changes, click Commit changes. This will automatically create a fork of the docs in your GitHub account with the changes.
Once you have committed your edits to your fork, follow the prompts to create a pull request and submit your changes for review.
Every pull request needs to be reviewed by our contributors and approved by a maintainer.
You can also read an annotated blog post with screenshots demonstrating the process of editing the docs this way.
Editing a local fork on github.com is convenient for small text changes, but does not allow you to see a live preview of the site.
You can instead open your fork in an online IDE (integrated development environment) for a code editor and live preview without needing to set up any local development environment. Each online IDE has its own shortcut URL for opening an existing repository, and will allow you to create pull requests after you have made changes.
See specific instructions for opening an existing repository in CodeSandbox, StackBlitz, Codeflow IDE and Gitpod on their respective websites.
Note that CodeSandbox and StackBlitz provide Astro syntax highlighting in their custom code editors, while Gitpod and Codeflow support the full Astro VSCode extension.
To begin developing locally, checkout this project from your machine.
git clone git@github.com:thewebforge/structeezy-docs.gitYou can install and run the project locally using pnpm. Head to the pnpm installation guide to get that set up. Then, run the following from your terminal:
pnpm install
pnpm startIf you’re copying these instructions, remember to configure this project as a fork.
git remote add upstream git@github.com:thewebforge/structeezy-docs.gitAt any point, create a branch for your contribution. We are not strict about branch names.
git checkout -b add/custom-structure-typo-fixOnce you have made your changes using any of the above methods, you’re ready to create a “Pull Request!”
This will let the Structeezy docs team know you have some changes to propose. At this point we can give you feedback and might request changes. For translations, we like to have at least one other person who knows the language you are translating into review the PR.
Read more about making a pull request in GitHub’s docs
Please include a clear title. The description will be pre-filled with questions that you can answer by editing right in the text field.
The docs site will be automatically updated whenever pull requests are merged.
On GitHub you’ll need a “fork” of this repository to work on. This is your own copy where you can make changes. Read more about forks in GitHub’s docs.
Not sure how to get started with GitHub, forks, pull requests, or want a quick refresher? You might want to check out this free video series:
How to Contribute to an Open Source Project on GitHub
To create your copy, click the Fork button at the top right of any page in this repository.
When you first create your fork, it will be an exact copy of this repository. Over time, thewebforge/structeezy-docs will change as the docs are updated, but your fork won’t automatically stay up-to-date. Here are some ways to keep your fork in sync with this repo.
- Navigate to your fork on GitHub
- Click Sync fork and then Update branch
In the terminal on your computer:
- Make sure you’re on the main branch:
git checkout main - Fetch and merge updates:
git pull upstream main - Push the updates back to your fork on GitHub:
git push origin main
- Go to the “Pull” GitHub app page
- Click Install
- Follow the instructions to select your fork