Skip to content

Commit

Permalink
Manually sync docs-and-website-components.md
Browse files Browse the repository at this point in the history 
For whatever reason, this page was not properly synced. This is a problem because this page contains relative imports that cause the build to break when sourced from a translation repo: gatsbyjs/gatsby#19036

Sync this page manually by just copy-pasting it from the main repo.
  • Loading branch information
@tesseralis
tesseralis authored Feb 26, 2020
1 parent 096ab0b commit a137ce8
Showing 1 changed file with 1 addition and 178 deletions.
179 changes: 1 addition & 178 deletions docs/contributing/docs-and-website-components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,6 @@ title: Docs and Website Components
tableOfContentsDepth: 2
---

import LayerModel from "../../www/src/components/layer-model"
import HorizontalNavList from "../../www/src/components/horizontal-nav-list"
import Breadcrumb from "../../www/src/components/docs-breadcrumb"
import { itemListContributing } from "../../www/src/utils/sidebar/item-list"
import TableOfContents from "../../www/src/components/docs-table-of-contents"

The Gatsbyjs.org site has a handful of components that have been developed to facilitate writing new content for the blog and the docs. There are also components that help organize and lay out content in various pages across the website.

This guide documents what components are available and explains how to use them. You can also refer to the [code for this page on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/docs-and-website-components.md) to see to how each component can be used, because they are all embedded here!
Expand Down Expand Up @@ -130,14 +124,6 @@ Rendered, the component looks like this:
To improve is to change, so to be perfect is to have changed often.
</Pullquote>

---

## Other available components

Other less commonly used components aren't globally available, but can imported at the top of a Markdown file and used in other docs.

---

### Layer Model

The `<LayerModel />` was made to help explain concepts of how Gatsby works at a high level. It conceptually breaks Gatsby into different layers and shows how data is pulled, aggregated, and eventually rendered as an app. It's used on docs pages to help explain how Gatsby works at different levels.
Expand Down Expand Up @@ -168,7 +154,7 @@ When used, it looks like this:

### Horizontal Navigation List

The `<HorizontalNavList />` was made for the [Glossary](/docs/glossary/), and renders a list of links to alphabetical subheadings on the page in a horizontal format. Because of its specific use case, it isn't made globally available but can be imported if needed on other pages.
The `<HorizontalNavList />` was made for the [Glossary](/docs/glossary/), and renders a list of links to alphabetical subheadings on the page in a horizontal format.

#### Usage

Expand Down Expand Up @@ -212,169 +198,6 @@ items={[
slug={props.slug}
/>

### Breadcrumb

The `<Breadcrumb />` component is used in layout files to display the hierarchy of pages a user is currently browsing on.

#### Usage

The Breadcrumb component takes one prop:

- `location` - an object provided in the props of page templates by default
- `itemList` - an object comprised of the docs hierarchical structure

<!-- prettier-ignore -->
```javascript
import Breadcrumb from "../../www/src/components/docs-breadcrumb"

<Breadcrumb location={props.location} itemList={itemList} />
```

_You can also refer to [an example of usage of the Breadcrumb in the Gatsbyjs.org source code](https://github.com/gatsbyjs/gatsby/blob/1d65ce051967dda5c4a89da920fc34692524e237/www/src/templates/template-docs-markdown.js#L82)_

#### Optional `breadcrumbTitle` entries in sidebar files

To alter the title of a doc that is displayed in the Breadcrumb component, a `breadcrumbTitle` is supported as a key in the [sidebar YAML files](https://github.com/gatsbyjs/gatsby/tree/master/www/src/data/sidebars). It is commonly used to provide an abbreviated version of a doc's title when displayed next to its parent page title, e.g. shortening "Adding a Custom webpack Config" to "webpack Config".

#### Sample

Rendered, it looks like this:

<Breadcrumb
location={{
pathname: "/contributing/docs-and-website-components/",
}}
itemList={itemListContributing}
/>

---

### Table of Contents

The `<TableOfContents />` component is used to render a list of subheaders from a docs page and automatically provide deep links to them.

#### Usage

The component takes 2 props:

- `location` - an object provided in the props of page templates by default
- `page` - an object with data passed in from the sites `gatsby-node.js` that contains information from the MDX plugin about the structure of headings

<!-- prettier-ignore -->
```javascript
import TableOfContents from "../../www/src/components/docs-table-of-contents"

<TableOfContents location={props.location} page={page} />
```

_You can also refer to [an example of usage of the Table of Contents in the Gatsbyjs.org source code](https://github.com/gatsbyjs/gatsby/blob/1d65ce051967dda5c4a89da920fc34692524e237/www/src/templates/template-docs-markdown.js#L121)_

The Table of Contents component also has some optional configurations that can be set in the frontmatter of a doc's markdown.

In docs where the Table of Contents isn't required and should be disabled, a key in the frontmatter called `disableTableOfContents` can be set to `true` like this:

```md
---
title: Glossary
disableTableOfContents: true
---

When you're new to Gatsby there can be a lot of words to learn...
```

In other docs where the Table of Contents is extremely long it can make sense to only show headers from the doc up to a certain level, rather than all subheadings. You can set the `tableOfContentsDepth` key to a number that will limit the subheadings shown in the table of contents to that "depth". If it is set to 2, `<h2>`/`##`, and `<h3>`/`###` headers will be listed, if set to 3, `<h2>`/`##`, `<h3>`/`###`, and `<h4>`/`####` will all be shown. It is set like this:

```md
---
title: Glossary
tableOfContentsDepth: 2
---

When you're new to Gatsby there can be a lot of words to learn...
```

#### Sample

The Table of Contents looks like this when rendered (and is also displayed on the right hand side of the page):

<TableOfContents
location={{ pathname: "/contributing/docs-and-website-components/" }}
page={{
frontmatter: {
title: "Docs and Website Components",
tableOfContentsDepth: 2,
},
tableOfContents: {
items: [
{
url: "#globally-available-components",
title: "Globally available components",
items: [
{
url: "#guide-list",
title: "Guide list",
},
{
url: "#egghead-embed",
title: "Egghead embed",
},
{
url: "#pull-quote",
title: "Pull quote",
},
],
},
{
url: "#other-available-components",
title: "Other available components",
items: [
{
url: "#layer-model",
title: "Layer model",
},
{
url: "#horizontal-navigation-list",
title: "Horizontal navigation list",
},
{
url: "#breadcrumb",
title: "Breadcrumb",
},
{
url: "#table-of-contents",
title: "Table of Contents",
},
],
},
{
url: "#writing-content-in-markdown",
title: "Writing content in markdown",
items: [
{
url: "#code-blocks",
title: "Code blocks",
},
],
},
{
url: "#styling-components-on-gatsbyjsorg-with-theme-ui",
title: "Styling components on Gatsbyjs.org with Theme-UI",
items: [
{
url: "#design-tokens",
title: "Design tokens",
},
{
url: "#the-sx-prop",
title: "The sx prop",
},
],
},
],
},
}}
/>

---

## Writing content in Markdown
Expand Down

0 comments on commit a137ce8

Please sign in to comment.