Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 74a6028

Browse files
gillkyleAisha Blake
gillkyle
and
Aisha Blake
authored
docs: move Breadcrumb and ToC component docs for i18n efforts (gatsbyjs#20913)
* move info for nav components in contributing docs, remove imports for i18n * Update docs/contributing/docs-contributions.md Co-Authored-By: Aisha Blake <[email protected]>
1 parent 4efb148 commit 74a6028

File tree

2 files changed

+42
-175
lines changed

2 files changed

+42
-175
lines changed

‎docs/contributing/docs-and-website-components.md

Lines changed: 0 additions & 175 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,6 @@ title: Docs and Website Components
33
tableOfContentsDepth: 2
44
---
55

6-
import Breadcrumb from "../../www/src/components/docs-breadcrumb"
7-
import { itemListContributing } from "../../www/src/utils/sidebar/item-list"
8-
import TableOfContents from "../../www/src/components/docs-table-of-contents"
9-
106
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.
117

128
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!
@@ -204,177 +200,6 @@ slug={props.slug}
204200

205201
---
206202

207-
## Other available components
208-
209-
Other less commonly used components aren't globally available, but can imported at the top of a Markdown file and used in other docs.
210-
211-
---
212-
213-
### Breadcrumb
214-
215-
The `<Breadcrumb />` component is used in layout files to display the hierarchy of pages a user is currently browsing on.
216-
217-
#### Usage
218-
219-
The Breadcrumb component takes one prop:
220-
221-
- `location` - an object provided in the props of page templates by default
222-
- `itemList` - an object comprised of the docs hierarchical structure
223-
224-
<!-- prettier-ignore -->
225-
```jsx
226-
import Breadcrumb from "../../www/src/components/docs-breadcrumb"
227-
228-
<Breadcrumb location={props.location} itemList={itemList} />
229-
```
230-
231-
_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)_
232-
233-
#### Optional `breadcrumbTitle` entries in sidebar files
234-
235-
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".
236-
237-
#### Sample
238-
239-
Rendered, it looks like this:
240-
241-
<Breadcrumb
242-
location={{
243-
pathname: "/contributing/docs-and-website-components/",
244-
}}
245-
itemList={itemListContributing}
246-
/>
247-
248-
---
249-
250-
### Table of Contents
251-
252-
The `<TableOfContents />` component is used to render a list of subheaders from a docs page and automatically provide deep links to them.
253-
254-
#### Usage
255-
256-
The component takes 2 props:
257-
258-
- `location` - an object provided in the props of page templates by default
259-
- `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
260-
261-
<!-- prettier-ignore -->
262-
```jsx
263-
import TableOfContents from "../../www/src/components/docs-table-of-contents"
264-
265-
<TableOfContents location={props.location} page={page} />
266-
```
267-
268-
_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)_
269-
270-
The Table of Contents component also has some optional configurations that can be set in the frontmatter of a doc's markdown.
271-
272-
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:
273-
274-
```markdown
275-
---
276-
title: Glossary
277-
disableTableOfContents: true
278-
---
279-
280-
When you're new to Gatsby there can be a lot of words to learn...
281-
```
282-
283-
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:
284-
285-
```markdown
286-
---
287-
title: Glossary
288-
tableOfContentsDepth: 2
289-
---
290-
291-
When you're new to Gatsby there can be a lot of words to learn...
292-
```
293-
294-
#### Sample
295-
296-
The Table of Contents looks like this when rendered (and is also displayed on the right hand side of the page):
297-
298-
<TableOfContents
299-
location={{ pathname: "/contributing/docs-and-website-components/" }}
300-
page={{
301-
frontmatter: {
302-
title: "Docs and Website Components",
303-
tableOfContentsDepth: 2,
304-
},
305-
tableOfContents: {
306-
items: [
307-
{
308-
url: "#globally-available-components",
309-
title: "Globally available components",
310-
items: [
311-
{
312-
url: "#guide-list",
313-
title: "Guide list",
314-
},
315-
{
316-
url: "#egghead-embed",
317-
title: "Egghead embed",
318-
},
319-
{
320-
url: "#pull-quote",
321-
title: "Pull quote",
322-
},
323-
],
324-
},
325-
{
326-
url: "#other-available-components",
327-
title: "Other available components",
328-
items: [
329-
{
330-
url: "#layer-model",
331-
title: "Layer model",
332-
},
333-
{
334-
url: "#horizontal-navigation-list",
335-
title: "Horizontal navigation list",
336-
},
337-
{
338-
url: "#breadcrumb",
339-
title: "Breadcrumb",
340-
},
341-
{
342-
url: "#table-of-contents",
343-
title: "Table of Contents",
344-
},
345-
],
346-
},
347-
{
348-
url: "#writing-content-in-markdown",
349-
title: "Writing content in markdown",
350-
items: [
351-
{
352-
url: "#code-blocks",
353-
title: "Code blocks",
354-
},
355-
],
356-
},
357-
{
358-
url: "#styling-components-on-gatsbyjsorg-with-theme-ui",
359-
title: "Styling components on Gatsbyjs.org with Theme-UI",
360-
items: [
361-
{
362-
url: "#design-tokens",
363-
title: "Design tokens",
364-
},
365-
{
366-
url: "#the-sx-prop",
367-
title: "The sx prop",
368-
},
369-
],
370-
},
371-
],
372-
},
373-
}}
374-
/>
375-
376-
---
377-
378203
## Writing content in Markdown
379204

380205
New docs and blog posts are added to the [docs](https://github.com/gatsbyjs/gatsby/tree/master/docs/) folder inside the Gatsby repository. They are stored as `.md` (Markdown) or `.mdx` (MDX) files and can be written using Markdown, or using inline JSX thanks to MDX. Writing in Markdown will output tags that are styled according to [Gatsby's design guidelines](/guidelines/color/).

‎docs/contributing/docs-contributions.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,48 @@ It can be necessary to change a heading within the docs. It's important to note
103103
- Determine the URL you're looking for. `Changing headers` is linked with a URL ending in `changing-headers`, `Docs renaming instructions` becomes `docs-renaming-instructions`, etc.
104104
- Update all instances of the old URL to your new one. [Find and replace](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) in VS Code can help. Check that the context of the original link reference still makes sense with the new one.
105105

106+
## Configuring site navigation
107+
108+
The docs include custom built components to aid with navigation. In order to customize the navigation experience, these components allow some configurations without changing any of the React code.
109+
110+
### Adjusting breadcrumb titles
111+
112+
The `<Breadcrumb />` component is used in layout files to display the hierarchy of pages a user is currently browsing on at the top of each doc.
113+
114+
To alter the title of a doc that is displayed in the Breadcrumb component, `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".
115+
116+
```yaml
117+
- title: Adding Page Transitions
118+
link: /docs/adding-page-transitions/
119+
breadcrumbTitle: Page Transitions # highlight-line
120+
```
121+
122+
### Disabling or shortening Table of Contents
123+
124+
The `<TableOfContents />` component is used to render a list of subheaders from a docs page and automatically provide deep links to them. It can be tweaked by values set in the frontmatter of a doc's markdown.
125+
126+
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:
127+
128+
```markdown
129+
---
130+
title: Glossary
131+
disableTableOfContents: true
132+
---
133+
134+
When you're new to Gatsby there can be a lot of words to learn...
135+
```
136+
137+
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:
138+
139+
```markdown
140+
---
141+
title: Glossary
142+
tableOfContentsDepth: 2
143+
---
144+
145+
When you're new to Gatsby there can be a lot of words to learn...
146+
```
147+
106148
## Adding embedded GraphQL examples
107149

108150
There are embedded examples in a few places in the docs (like the [GraphQL Reference guide](/docs/graphql-reference/)) that provide a working version of the code described. In the specific example of the GraphQL Query Options Reference page, these examples of the GraphiQL interface show how data can be queried from Gatsby's data layer.

0 commit comments

Comments
 (0)