Skip to content

Commit d3d6b53

Browse files
fkfk
authoredMar 12, 2019
feat(docs): Link to main sections from /docs/ (#12529)
- add landing pages for - Guides - API Reference - Releases & Migration - Conceptual Guide - Advanced Tutorials to `docs/docs/`; their intro paragraph is taken from the copy at `www/src/pages/docs/index` / https://www.gatsbyjs.org/docs/ - link those in `www/src/data/doc-links.yaml` and `www/src/pages/docs/index` - `/docs/guides/` - `/docs/api-reference/` - `/docs/releases-and-migration/` - `/docs/conceptual-guide/` - `/docs/advanced-tutorials/` - link „Ecosystem“ and „Advanced Tutorials“ in `www/src/pages/docs/index` Slightly tweak `www/src/templates/template-docs-markdown`: Change „Guides in this section“ headline preceding the list of child articles to say „In this section“, thus making it work for non „Guides“ articles (e.g. the newly added landing pages).
·
v2.20.0babel-plugin-remove-graphql-queries@2.6.3
1 parent a5dbe7e commit d3d6b53

File tree

8 files changed

+76
-29
lines changed

8 files changed

+76
-29
lines changed
 

‎docs/docs/advanced-tutorials.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Advanced Tutorials
3+
overview: true
4+
---
5+
6+
Learn about topics that are too large for a doc and warrant a tutorial.
7+
8+
[[guidelist]]

‎docs/docs/api-reference.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: API Reference
3+
overview: true
4+
---
5+
6+
Learn more about Gatsby APIs and configuration.
7+
8+
[[guidelist]]

‎docs/docs/conceptual-guide.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Conceptual Guide
3+
overview: true
4+
---
5+
6+
Read high-level overviews of the Gatsby approach.
7+
8+
[[guidelist]]

‎docs/docs/guides.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Guides
3+
overview: true
4+
---
5+
6+
Dive deeper into different topics around building with Gatsby, like sourcing data, deployment, and more.
7+
8+
[[guidelist]]

‎docs/docs/releases-and-migration.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: "Releases & Migration"
3+
overview: true
4+
---
5+
6+
Find release notes and guides for migration between major versions.
7+
8+
[[guidelist]]

‎www/src/data/sidebars/doc-links.yaml

+5
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
- title: Recipes
88
link: /docs/recipes/
99
- title: Guides
10+
link: /docs/guides/
1011
items:
1112
- title: Preparing Your Environment
1213
link: /docs/preparing-your-environment/
@@ -288,6 +289,7 @@
288289
- title: Awesome Gatsby Resources
289290
link: /docs/awesome-gatsby/
290291
- title: API Reference
292+
link: /docs/api-reference/
291293
items:
292294
- title: Gatsby Link
293295
link: /docs/gatsby-link/
@@ -306,6 +308,7 @@
306308
- title: API Philosophy
307309
link: /docs/api-specification/
308310
- title: Releases & Migration
311+
link: /docs/releases-and-migration/
309312
items:
310313
- title: v2 Release Notes
311314
link: /docs/v2-release-notes/
@@ -316,6 +319,7 @@
316319
- title: Migrating from v0 to v1
317320
link: /docs/migrating-from-v0-to-v1/
318321
- title: Conceptual Guide
322+
link: /docs/conceptual-guide/
319323
items:
320324
- title: The Gatsby Core Philosophy*
321325
link: /docs/gatsby-core-philosophy/
@@ -386,6 +390,7 @@
386390
- title: Terminology
387391
link: /docs/behind-the-scenes-terminology/
388392
- title: Advanced Tutorials
393+
link: /docs/advanced-tutorials/
389394
items:
390395
- title: Making a Site with User Authentication
391396
link: /docs/authentication-tutorial/

‎www/src/pages/docs/index.js

+21-16
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ class IndexRoute extends React.Component {
3535
to dig straight in.
3636
</li>
3737
<li>
38-
<Link to="/docs/recipes">Recipes</Link>: A happy medium between
38+
<Link to="/docs/recipes/">Recipes</Link>: A happy medium between
3939
the tutorial and the quick start, find some quick answers for
4040
how to accomplish some specific, common tasks with Gatsby.
4141
</li>
@@ -45,33 +45,38 @@ class IndexRoute extends React.Component {
4545
</li>
4646
<ul>
4747
<li>
48-
<strong>Guides</strong>: Dive deeper into different topics
49-
around building with Gatsby, like sourcing data, deployment,
50-
and more.
48+
<Link to="/docs/guides/">Guides</Link>: Dive deeper into
49+
different topics around building with Gatsby, like sourcing
50+
data, deployment, and more.
5151
</li>
5252
<li>
53-
<strong>Ecosystem</strong>: Check out libraries for Gatsby
54-
starters and plugins, as well as external community resources.
53+
<Link to="/ecosystem/">Ecosystem</Link>: Check out libraries
54+
for Gatsby starters and plugins, as well as external community
55+
resources.
5556
</li>
5657
<li>
57-
<strong>API Reference</strong>: Learn more about Gatsby APIs
58-
and configuration.
58+
<Link to="/docs/api-reference/">API Reference</Link>: Learn
59+
more about Gatsby APIs and configuration.
5960
</li>
6061
<li>
61-
<strong>Releases &amp; Migration</strong>: Find release notes
62-
and guides for migration between major versions.
62+
<Link to="/docs/releases-and-migration/">
63+
Releases &amp; Migration
64+
</Link>
65+
: Find release notes and guides for migration between major
66+
versions.
6367
</li>
6468
<li>
65-
<strong>Conceptual Guide</strong>: Read high-level overviews
66-
of the Gatsby approach.
69+
<Link to="/docs/conceptual-guide/">Conceptual Guide</Link>:
70+
Read high-level overviews of the Gatsby approach.
6771
</li>
6872
<li>
69-
<strong>Behind the Scenes</strong>: Dig into how Gatsby works
70-
under the hood.
73+
<Link to="/docs/behind-the-scenes/">Behind the Scenes</Link>:
74+
Dig into how Gatsby works under the hood.
7175
</li>
7276
<li>
73-
<strong>Advanced Tutorials</strong>: Learn about topics that
74-
are too large for a doc and warrant a tutorial.
77+
<Link to="/docs/advanced-tutorials/">Advanced Tutorials</Link>
78+
: Learn about topics that are too large for a doc and warrant
79+
a tutorial.
7580
</li>
7681
</ul>
7782
</ol>

‎www/src/templates/template-docs-markdown.js

+10-13
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,8 @@ import Container from "../components/container"
1515

1616
import docsHierarchy from "../data/sidebars/doc-links.yaml"
1717

18-
// I’m doing some gymnastics here that I can only hope you’ll forgive me for.
19-
// Find the guides in the sidebar YAML.
20-
const guides = docsHierarchy.find(group => group.title === `Guides`).items
21-
22-
// Search through guides tree, which may be 2, 3 or more levels deep
23-
const childItemsBySlug = (guides, slug) => {
18+
// Search through tree, which may be 2, 3 or more levels deep
19+
const childItemsBySlug = (docsHierarchy, slug) => {
2420
let result
2521

2622
const iter = a => {
@@ -31,7 +27,7 @@ const childItemsBySlug = (guides, slug) => {
3127
return Array.isArray(a.items) && a.items.some(iter)
3228
}
3329

34-
guides.some(iter)
30+
docsHierarchy.some(iter)
3531
return result && result.items
3632
}
3733

@@ -40,14 +36,15 @@ const getPageHTML = page => {
4036
return page.html
4137
}
4238

43-
const guidesForPage = childItemsBySlug(guides, page.fields.slug) || []
44-
const guideList = guidesForPage
45-
.map(guide => `<li><a href="${guide.link}">${guide.title}</a></li>`)
39+
const subitemsForPage =
40+
childItemsBySlug(docsHierarchy, page.fields.slug) || []
41+
const subitemList = subitemsForPage
42+
.map(subitem => `<li><a href="${subitem.link}">${subitem.title}</a></li>`)
4643
.join(``)
47-
const toc = guideList
44+
const toc = subitemList
4845
? `
49-
<h2>Guides in this section:</h2>
50-
<ul>${guideList}</ul>
46+
<h2>In this section:</h2>
47+
<ul>${subitemList}</ul>
5148
`
5249
: ``
5350

0 commit comments

Comments
 (0)
Please sign in to comment.