Share your troubleshooting tips and best practices with the community by contributing to the Adobe Commerce Support Knowledge Base (Support Knowledge Base)! You can contribute by creating an issue or pull request (PR) on our support knowledge base GitHub repository. We welcome all types of contributions; from minor typo fixes to new topics.
The support knowledge base staff members review issues and pull requests on a regular basis. We do our best to address all issues as soon as possible, but working through the backlog takes time. We appreciate your patience.
The support knowledge base works with Magento Community Engineering teams and projects. As you contribute PRs, you gain Contribution Points.
- Make sure you have a GitHub account.
- Fork the Support Knowledge Base repository. Remember to sync your fork and update branches as needed.
- Review the Support Knowledge Base guidelines below.
Note for partners: Add 2FA protection when contributing to Magento repositories.
The following diagram shows the contribution workflow:
- Create a new branch from your fork using a name that best describes the work or references a GitHub issue number.
- Edit or create markdown (
.md) files in your branch. - Push your branch to your fork.
- Create a pull request to the magento/knowledge-base repository. Use
mainas the base branch when creating a PR. - Complete the pull request providing the information listed in the template.
- We will close your pull request if you do not provide the information described in the template.
- After creating a pull request, a Support KB staff member will review it and may ask you to make revisions.
- We will close your pull request if you do not respond to feedback in two weeks.
Note: If you have not signed the Adobe Contributor License Agreement, the pull request provides a link. You must sign the CLA before we can accept your contribution.
- Review existing pull requests and issues to avoid duplicating work.
- For large contributions, or changes that include multiple files, open an issue and discuss it with us first. This helps prevent duplicate or unnecessary work.
- Do not make global find-and-replace changes without first creating an issue and discussing it with us. Global changes can have unintended consequences.
- Combine multiple small changes (such as minor editorial and technical changes) into a single pull request. This helps us efficiently and effectively facilitate your contribution.
- Review your work for basic typos, formatting errors, or ambiguous sentences before opening a pull request.
The following guidelines may answer most of your questions and help you get started.
- Write content using Markdown. See Support KB formatting for details.
- Please follow the style recommendations described in Support KB Styleguide.
- Use article templates when adding new articles.
- Follow the recommended file structure and file naming convention described below.
- Test your changes & additions for linting errors before creating a pull request - this will save time and effort as errors will cause the automatic checks to fail and will need fixing before the pull request can be merged.
- Do not make changes to content in the Announcements and Support Tools folders.
- Do not remove/change the HTML formatting mentioned as required in Support KB formatting.
- Do not remove/change the HTML formatting in Troubleshooters articles. Examples:
Contributions can be tested locally using the 'mdl' application. Full instructions on how to install and use 'mdl' can be found on the Markdown Lint repository.
Run :
mdl --style=_checks/styles/style-rules-prod --ignore-front-matter --git-recurse -- .If no errors are returned then it is safe to commit changes and create a pull request. See Linting Error Codes for an explanation of any errors reported.
For more advanced checking and identifying of linting issues, the linter-markdownlint plugin from Atom can be installed alongside mdl.
All .md files should go to sections folders, nested in category folders under the "src" folder. All image attachments should go to "assets" folders inside the section folders.
Contributors should also note that we only accept attachments in .png, .jpg, and .jpeg formats.
All file and folder names must be lower cased with "-" in between all words. File names should be descriptive and might coincide with future article title (but they don't define the title).
If you add images to your articles, please follow this convention to name your image files:
- Specify the version of the product which is represented on the screenshot. If it is not Adobe Commerce, add the name of the product to the file name.
- Relay what is being captured by the image, for example, a screenshot of Adobe Commerce Price Rule configuration would be cart-price-rule-new-231.png, cart-price-rule-saved-231.png etc. Check for existing images to follow the naming patterns.
- File names are in lower case.
- Words should be separated by a hyphen "-", not underscore "_".
- Use existing naming patterns. Check the existing file names under /assets folders as an example.
The Markdown (.md) file's metadata is a set of YAML key-value pairs. The metadata section is located at the top of each file. Non-ASCII characters are not allowed in metadata. See Metadata validation guide to avoid/fix validation errors.
---
title:
labels:
---Key-value pair reference:
| Property | Description |
|---|---|
title |
Defines the article title. If using any YAML special characters in title, please enclose it in quotes ("") |
labels |
Contains labels that will be added to the article in the support knowledge base. Add labels to describe products, issues, products versions, section and category. If in doubt, don't add labels. |
To add an article, create a new markdown file in the desired category + section. Articles must include the standard metadata table with title and labels. Labels can be omitted.
You can rename an article, edit its content, labels, or links to files.
To rename the article, update the title in the article's metadata. It will reflect in Support Help Center exactly as written in the metadata. Non-ASCII characters are not allowed in metadata.
To add, edit, or delete article labels (tags), update the labels portion of the metadata.
To edit the article body, edit the body within your editor. Follow our Formatting guide.
To move an article into a different section, move the file into the appropriate section. Do not move your article directly into a category folder. This will result in errors.
To delete an article, delete the article file.
If you find a typo or errors in the support knowledge base article, you can either correct it and deliver changes with a pull request (as described above), or you can report it by creating an issue in the Support KB repository.
You must complete the issue template. We will close your issue if you fail to provide the information listed template. Enter as much information as you can, including content corrections, steps to reproduce, command or code updates, or questions for clarifications.
Note: Check the existing issues on GitHub to see if someone has already reported the issue.
Thank you for contributing your brilliance to the Adobe Commerce Support Knowledge Base!!