Skip to content

Latest commit

 

History

History
215 lines (154 loc) · 8.56 KB

CONTRIBUTING_DESIGN.md

File metadata and controls

215 lines (154 loc) · 8.56 KB
Raw

/docs & 11ty documentation

The Red Hat Digital Design System site is built with Eleventy.

Installation

To work on the site on your local machine, follow the setup instructions in the developers' contributing guide

Running Local Server

Once set up, run the 11ty development server with the following command:

npm run serve

This will start eleventy and a watch process that will reload the site if *.njk, *.md, *.scss, or *.js files under /docs are updated.

Publishing Your Changes

To publish your changes, commit them to a new git branch and create a pull request RHDS follows the conventional commits. For changes to ux.redhat.com, please use the docs: commit type. For more information, see the pull request review guidelines.

Once you've opened the PR, request a review from a member of the design team, and optionally a member of the development team. Shortly after your PR is opened, netlify will build a deploy preview and leave a comment in the PR discussion with a link to preview your changes.

When the PR is approved, and all required checks pass, it can be merged into main. All commits to main trigger a redeploy in Netlify. If you are a member of the RedHat-UX netlify team, you can track the progress of the deploy on the Netlify dashboard. Assuming nothing unexpected happens, your changes should be live within a few minutes of merging.

Folders

docs/

The pages dir contains files that will be turned into web pages, in an identical folder structure. These files can be .njk or .md.

See the PAGES-11ty-documentation.md for more information.

docs/scss/ and docs/assets/

This is where our CSS and JS source files live, they're compiled by gulp with source maps if compiling for dev and minified if we're compiling for production.

_site/

Directory to be hosted as webroot. All files are ignored.

Authoring

Front matter, and you

Each content file has a bit at the top we call 'front matter'. This provides metadata that will be used as content, for sorting, in templating,etc.

Most pages should have front matter that looks like this:

---
layout: layouts/pages/basic.njk
title: Grid
order: -10
tags:
  - foundations
---
  • layout: decides what the page template will be used
  • title: What the page title is, this is used for the title that shows in the tab of the browser and the h1 on most page templates.
  • order: Helps effect how items are sorted. See Sorting below.
  • tags: Tags can be used for all sorts of things, at time of writing, they are used to help build the navigation. tags is multivalue, so a page could have multiple tags if we wanted.

Getting pages into the navigation

The navigation is an included template: pages/partials/component/sidenav.njk

It is a mixture of hardcoding and dynamic listing so that it's hopefully easy to understand.

The navigation is in a nested ul, the top level menu links and the second level 'Overview' links are all hardcoded and can be added by copying an existing li and it's contents as needed.

The details elements have a for statement that finds all pages with the listed tag, e.g. {%- for foundation in collections.foundations -%} is iterating over all of the pages with the tag foundations.

Tags and navigation sections can be added by copying a similar section and updating the content as needed.

Adding new tags

New tags can be added by adding them to a pages front matter, there is nothing else that has to be done for it to exist and be used by collections.

If the new tag needs to be sorted in any special way it needs to be handled in: .eleventy.js.

Sorting

There is an existing sort function that we're using on tags that show up in the navigation. To add a new tag to the existing sort, add it to the tagsToAlphabetize array in .eleventy.js.

The sort logic we have is as follows:

  • It sorts by order, and then alphabetically by title, those values both coming from the front matter of the pages.
  • If order isn't in the frontmatter, it's assumed the order is 0.
  • order is sorted like weight: the larger the number, the more it sinks; the lower the number, the higher it floats.
  • If all files have no order value, or the same order value, they will simply be listed alphabetically by title.

Let's say we have the following page title's and orders:

  • Dang that was a Great Title
    • order: 0
  • A Cool Title
    • No order set
  • Being a Witty Title
    • order: 10
  • Can We Make a Better Title
    • order: -10

The result would be:

  • Can We Make a Better Title
  • A Cool Title
  • Dang that was a Great Title
  • Being a Witty Title

Because:

  • Can We Make a Better Title has the lowest order, and then floats to the top
  • Being a Witty Title has the largest order and sinks to the bottom
  • A Cool Title and Dang that was a Great Title both have the same order value of 0, so are ordered alphabetically, A coming before D

11ty is an unopinionated static site generator. It gives us a lot of basic features that are handy when templating, organizing, and building a site, but mostly tries to stay out of our way.

This site is configured to use Nunjucks and Markdown as languages to build pages.

Each page should have 'front-matter'. Front-matter should be at the top of the document, it helps define page templates, tags, and other variables we may use to help display or organize our pages.

Here's a two simple examples:

---
layout: layouts/pages/basic.njk
title: Example page
---
---
layout: layouts/pages/home.njk
title: Home
---

This tells 11ty what the page template should be (relative to the pages folder), and what the page title is. Which may be used as part of the page template as an h1, but is also used as part of the <title> attribute in the <head>.l

Here's an example including tags, which is a multi-value piece of data.

---
layout: layouts/pages/basic.njk
title: Accordion Element
tags:
  - javascript
  - container
---

Front-matter variables can be arbitrarily defined and used in templates or for custom javascript coding, although there are some values that are predefined by 11ty.

Adding Component JS to a page

To add a Patternfly Element's JS, add an entry to the front-matter includeComponent and a list of the components to be used on the page:

---
layout: layouts/pages/basic.njk
title: Card
tags:
  - component
includeComponent:
  - pfe-card
  - pfe-tabs
---

To make sure it has been loaded, check the 'Network' tab in the dev tools of the web browser. Filter by the name of the component (e.g. pfe-card) and make sure it exists in the project.

If it does not, any new Patternfly elements can be added to the project by installing them with npm, e.g.:

npm install @patternfly/pfe-foo-bar

Nunjucks' Macros

Macros are essentially HTML Mixins. They don't print anything until they're called, they take parameters, and have self contained logic and markup to be printed.

See a simple example at pages/component/documentation.njk.

To use it in another file, first import it in the file containing the mixin:

{% import "component/documentation.njk" as documentation %}

The first param is the file location relative to pages/ (11ty root), the second parameter is a reference to the exports (e.g. macros) of the file. We can call the 'output' macro in the file with dot notation.

So to print it in a page we'd use:

  {{ documentation.output() }}

If the macro took parameters we can include them in the parentheses.

Files with macros can have all sorts of other content, which won't print if it's pulled in with import. This means the file with a macro can detail a component in our library and show multiple variants of the component, and if we want to include it in another file we can call the file and only pull in the macro with params of our choosing if we want.

If you would like to pull in an entire file's display, use include.