Thank you for your interest in Palo Alto Networks developer documentation!
- Types of contributions
- Use GitHub and Git
- Using markdown and MDX
- CLI and code snippets
- Adding a document
- More resources
Types of contributions
The following are ways you can contribute to Palo Alto Networks developer docs:
- Author and contribute documentation via the developer site repository.
- Report documentation bugs/issues under the developer site repository
- Request new documentation by opening a request under the developer site repository
Using Git and GitHub
Setting up your fork of the repository
- Create a GitHub account. If you haven't done this already, please join GitHub now.
- Set up
giton your machine. Follow the instructions in the Getting Started tutorial.
- Fork the developer site repo. To do this, click the Fork button in the upper-right corner of the main repo page.
- Clone your fork to your local machine using the following command:
Next, create a reference to the root repository by entering these commands:
Congratulations! You've now set up your repository.
To make the contribution process as seamless as possible for you, follow this procedure.
- Create a new branch.
- Add or edit existing content.
- Push changes to your forked repo.
- Use GitHub to create a New pull request.
- After the pull request is approved and merged, you may delete the branch.
Try to limit each specific contribution or edit to a branch to help reduce the likelihood of conflicts.
The following are examples of contributions appropriate for a new branch:
- New content
- New or updated media, e.g. images, video, etc.
- Grammar and typo corrections
- Formatting changes
Sync forked repo with root
After some time has passed, it might be necessary to sync your local repo with the remote, upstream repo.
- Fetch remote upstream
upstream/masterwith local and
Markdown and MDX
MDX syntax can be boiled down to being JSX in Markdown. It’s a superset of Markdown syntax that also supports importing, exporting, and JSX. If you're planning use MDX to author your content be sure to use the
.mdx file extension when naming your file.
Getting started with MDX.
All of the articles in this repository use Markdown and MDX. While a complete introduction (and listing of all the syntax) can be found here, let's cover some of the basics first.
This is a list of the most common markdown syntax:
Line breaks vs. paragraphs: In Markdown there is no HTML
<br />element. Instead, a new paragraph is designated by an empty line between two blocks of text.
Italics: The HTML
<i>some text</i>is written
Bold: The HTML
<strong>some text</strong>element is written
Headings: HTML headings are designated by an number of
#characters at the start of the line. The number of
#characters corresponds to the hierarchical level of the heading (for example,
##= h2, and
Numbered lists: To create a numbered (ordered) list, start the line with
1.. If you want multiple elements within a single list element, format your list as follows:
Notice that there is a space after the '.'
Now notice that there is a line break between the two paragraphs in the list element, and that the indentation here matches the indentation of the line above.
Bulleted lists: Bulleted (unordered) lists are almost identical to ordered lists except that the
1.is replaced with either
+. Multiple element lists work the same way as they do with ordered lists.
Links: The base syntax for a link is
[visible link text](link url). Links can also have references, which is discussed in the Link and Image References section below.
Images: The base syntax for an image is
![alt text for the image](image url). Images can also have references, which is discussed in the Link and Image References section below.
In-line HTML: Markdown allows you to include HTML inline, but this should be avoided.
Link and image references
Markdown has a really nice feature that lets a user insert a reference instead of a URL for images and links. Here is the syntax for using this feature:
By using references grouped at the bottom of your file, you can easily find, edit, and reuse link and image URLs.
CLI and code snippets
When using code blocks try to ensure your example is ready to copy and paste. Consider that a reader may be a beginner with no understanding of the difference between a shell prompt and a command. The same applies to inline comments.
Not this (results in a "command not found" error):
Adding a document
This section describes the general steps required for adding a document using
Each doc requires a frontmatter header, which Docusaurus uses to determine the following:
- What description, title and tags to inject into the HTML
- What sidebar and sidebar category to organize the document under
- A unique document ID
If you're not sure where to begin, feel free to use an existing doc as boilerplate. Just remember that each document requires a unique ID.
Each developer site will implement one or more documentation sidebars, depending on the number of vertical content areas covered by that site. The relationship between docs, categories and sidebars can be summarized as follows (listed in hierarchical order from left to right):
The sidebar is generated from the
sidebars.js file located in the root folder.
The following snippet calls out each specific sidebar component (note that the actual
sidebars.js file should not contain comments).
Contributing a doc
Contributing a new document can be achieved with the following, high-level flow:
- Create a new MD/MDX file under the
- Add the appropriate frontmatter (including the unique ID)
- Add the document ID to an existing or new sidebar/sidebar category