Guidelines for PatternFly.org content

These guidelines provide details about how PatternFly's web documentation should be set up and written.

Table of contents

• Getting started
• Creating new webpages
• Editing existing webpages
  • Design guidelines
  • Images

---

Getting started

1. Depending on the type of documentation you’re writing, conduct research as necessary, to be inclusive of industry best practices and standards. PatternFly.org documentation is written in Markdown and organized in the documentation-site folder of the repo.

2. To update content on PatternFly.org, refer to the contribution guide.

3. At any time, you can click the preview icon at the top right of your VS Code file. This will load a preview window that gives a better idea of the final file styling:

   

---

Creating new webpages

Most often, contributors will be working on existing content. If you're working on an entirely new piece of documentation, you'll need to create a new file via these steps:

1. Open up the correct folder, using the help of the directory above.

2. Create a new folder by right clicking on the components node, and clicking “New folder”. Name it the same name of the new component , in lowercase with dashes in place of spaces.

   

3. Inside your new folder, create:

   • An md file named after the component you will be adding guidelines to ("button.md")

   • A folder titled "img" where you will be storing all the images inserted in the guidelines.

     For example, if you're creating guidelines for a component called “testing-test”, your file structure would look like this:

     

File metadata

All PatternFly documentation files must include a few identifiers at the top of the file, in order to properly render the file content on the website. Metadata options include:

• section: (Required) The navigation section that contains this page. For example
• subsection: (Optional) If applicable, the 2nd layer of navigation. Only for pages that are nested within the navigation.
• id: (Required) The nav label for this page. For example, “Select”. Also sets the page name.
• source: (Optional) The tab label for this page.
• title: (Optional) The page title, if you want the page name to be different than the value for id.
• sortValue: (Optional) The place in the nav to place this page, if you need to override the default alphabetical sorting.

In most cases, you will only need to use the required fields: “section” and “id”, but the other options can be leveraged for more complex situations.

The file metadata should be placed between 2 sets of 3 hyphens (---) at the top of your markdown file:

---

Editing existing webpages

If you're working on updates to an existing content file:

1. Locate the proper folder in VS Code. If you want to work on an existing file, but can't figure out where it's located in the file tree, try clicking the “View source on GitHub” link at the bottom of the page on PatternFly.org.

<img width="400" alt="Screenshot 2025-02-14 at 1 33 20 PM" src="https://github.com/user-attachments/assets/14db2f65-a83e-46f9-892a-07e262f85c04" />

1. Open the markdown file inside the folder, and edit from there.

Design guidelines

Design guideline documents are located in the content > design-guidelines folder of the patternfly-org repo. There are 7 subfolders of design guidelines:

1. Charts: Guidelines for different chart types
2. Components: Component design guidelines (most likely what you will be updating)
3. Content: Guidelines for UX-Writing, and writing microcopy
4. Extensions: Guidelines for extensions
5. Layouts: Guidelines for layout types
6. Patterns: Guidelines for patterns
7. Styles: Visual design resources and styles
8. Usage and behavior: Some additional design patterns

Within the "Components" folder, each component has its own respective folder with:

• An “img” folder for images where all images used in that component’s design guidelines are stored.
• An .md file, which is the markdown file for that component where you will make your text/image edits.

For example, in this image you can see that the “About modal” component has its own folder, with an image (img) folder and markdown (.md) file.

Images

You can create images to illustrate concepts and provide readers with relevant visual examples. PatternFly.org image assets are contained in the PatternFly 6: Design Guidelines Figma file. If you need editing access for this file, reach out to the PatternFly team via the list-patternfly Slack channel.

To add or replace an image within a markdown file:

1. Export your image file from Figma. To ensure we're using high-quality images in our final documentation, export images as SVG files.
2. Drag the exported image file into the img folder for the component. If you are replacing an existing image, click “Replace” when the pop up comes up.
3. In the markdown file for the component:

   1. Add import '../components.css';beneath the file metadata at the top.

   2. Type in the following HTML tag where you want to add the picture (make sure to edit the filename and accessibility text):

      <div class="ws-docs-content-img">
      ![Alt text](./img/filename.svg)
      </div>
      

---

Get help

If you run into issues with this guide, or if you have any questions, reach out to Erin Donehoo (edonehoo).