Skip to content

Commit ad98009

Browse files
jescalanjescalan
committed
🌷 Docs Website Maintenance (hashicorp#11696)
* update dependencies, upgrade product downloader, use new docs component provider * custom components readme docs, remove old distributed tabs component
1 parent 36943c3 commit ad98009

File tree

12 files changed

+767
-762
lines changed

12 files changed

+767
-762
lines changed

‎website/README.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,125 @@ There are several custom markdown plugins that are available by default that enh
116116

117117
...while it perhaps would not be an improved user experience, no links would break because of it. The best approach is to **avoid changing headlines and inline code at the start of a list item**. If you must change one of these items, make sure to tag someone from the digital marketing development team on your pull request, they will help to ensure as much compatibility as possible.
118118

119+
### Custom Components
120+
121+
A number of custom [mdx components](https://mdxjs.com/) are available for use within any `.mdx` file. Each one is documented below:
122+
123+
#### Tabs
124+
125+
The `Tabs` component creates tabbed content of any type, but is often used for code examples given in different languages. Here's an example of how it looks from the Vagrant documentation website:
126+
127+
![Tabs Component](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALZ4/Screen%20Recording%202020-06-11%20at%2006.03%20PM.gif?v=1de81ea720a8cc8ade83ca64fb0b9edd)
128+
129+
It can be used as such within a markdown file:
130+
131+
````mdx
132+
Normal **markdown** content.
133+
134+
<Tabs>
135+
<Tab heading="CLI command">
136+
<!-- Intentionally skipped line.. -->
137+
```shell-session
138+
$ command ...
139+
```
140+
<!-- Intentionally skipped line.. -->
141+
</Tab>
142+
<Tab heading="API call using cURL">
143+
144+
```shell-session
145+
$ curl ...
146+
```
147+
148+
</Tab>
149+
</Tabs>
150+
151+
Contined normal markdown content
152+
````
153+
154+
The intentionally skipped line is a limitation of the mdx parser which is being actively worked on. All tabs mst have a heading, and there is no limit to the number of tabs, though it is recommended to go for a maximum of three or four.
155+
156+
#### Enterprise Alert
157+
158+
This component provides a standard way to call out functionality as being present only in the enterprise version of the software. It can be presented in two contexts, inline or standalone. Here's an example of standalone usage from the Consul docs website:
159+
160+
![Enterprise Alert Component - Standalone](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALp8/Screen%20Shot%202020-06-11%20at%206.06.03%20PM.png?v=d1505b90bdcbde6ed664831a885ea5fb)
161+
162+
The standalone component can be used as such in markdown files:
163+
164+
```mdx
165+
# Page Headline
166+
167+
<EnterpriseAlert />
168+
169+
Continued markdown content...
170+
```
171+
172+
It can also receive custom text contents if you need to change the messaging but wish to retain the style. This will replace the text `This feature is available in all versions of Consul Enterprise.` with whatever you add. For example:
173+
174+
```mdx
175+
# Page Headline
176+
177+
<EnterpriseAlert>
178+
My custom text here, and <a href="#">a link</a>!
179+
</EnterpriseAlert>
180+
181+
Continued markdown content...
182+
```
183+
184+
It's important to note that once you are adding custom content, it must be html and can not be markdown, as demonstrated above with the link.
185+
186+
Now let's look at inline usage, here's an example:
187+
188+
![Enterprise Alert Component - Inline](https://p176.p0.n0.cdn.getcloudapp.com/items/L1upYLEJ/Screen%20Shot%202020-06-11%20at%206.07.50%20PM.png?v=013ba439263de8292befbc851d31dd78)
189+
190+
And here's how it could be used in your markdown document:
191+
192+
```mdx
193+
### Some Enterprise Feature <EnterpriseAlert inline />
194+
195+
Continued markdown content...
196+
```
197+
198+
It's also worth noting that this component will automatically adjust to the correct product colors depending on the context.
199+
200+
#### Other Components
201+
202+
Other custom components can be made available on a per-site basis, the above are the standards. If you have questions about custom components that are not documented here, or have a request for a new custom component, please reach out to @hashicorp/digital-marketing.
203+
204+
### Syntax Highlighting
205+
206+
When using fenced code blocks, the recommendation is to tag the code block with a language so that it can be syntax highlighted. For example:
207+
208+
````
209+
```
210+
// BAD: Code block with no language tag
211+
```
212+
213+
```javascript
214+
// GOOD: Code block with a language tag
215+
```
216+
````
217+
218+
Check out the [supported languages list](https://prismjs.com/#supported-languages) for the syntax highlighter we use if you want to double check the language name.
219+
220+
It is also worth noting specifically that if you are using a code block that is an example of a terminal command, the correct language tag is `shell-session`. For example:
221+
222+
🚫**BAD**: Using `shell`, `sh`, `bash`, or `plaintext` to represent a terminal command
223+
224+
````
225+
```shell
226+
$ terraform apply
227+
```
228+
````
229+
230+
✅**GOOD**: Using `shell-session` to represent a terminal command
231+
232+
````
233+
```shell-session
234+
$ terraform apply
235+
```
236+
````
237+
119238
<!-- END: editing-markdown -->
120239

121240
<!-- BEGIN: editing-docs-sidebars -->

‎website/components/tabs/README.md

Lines changed: 0 additions & 61 deletions
This file was deleted.

‎website/components/tabs/index.jsx

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎website/components/tabs/style.module.css

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎website/layouts/docs.jsx

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
11
import DocsPage from '@hashicorp/react-docs-page'
22
import order from '../data/docs-navigation.js'
33
import { frontMatter as data } from '../pages/docs/**/*.mdx'
4-
import { MDXProvider } from '@mdx-js/react'
54
import Head from 'next/head'
65
import Link from 'next/link'
7-
import Tabs, { Tab } from '../components/tabs'
6+
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
87
import Button from '@hashicorp/react-button'
98

10-
const DEFAULT_COMPONENTS = { Tabs, Tab, Button }
9+
const MDXProvider = createMdxProvider({
10+
product: 'vagrant',
11+
additionalComponents: { Button },
12+
})
1113

1214
function DocsLayoutWrapper(pageMeta) {
1315
function DocsLayout(props) {
1416
return (
15-
<MDXProvider components={DEFAULT_COMPONENTS}>
17+
<MDXProvider>
1618
<DocsPage
1719
{...props}
1820
product="vagrant"

‎website/layouts/intro.jsx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
import DocsPage from '@hashicorp/react-docs-page'
22
import order from '../data/intro-navigation.js'
33
import { frontMatter as data } from '../pages/intro/**/*.mdx'
4-
import { MDXProvider } from '@mdx-js/react'
4+
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
55
import Head from 'next/head'
66
import Link from 'next/link'
77

8-
const DEFAULT_COMPONENTS = {}
8+
const MDXProvider = createMdxProvider({ product: 'vagrant' })
99

1010
function IntroLayoutWrapper(pageMeta) {
1111
function IntroLayout(props) {
1212
return (
13-
<MDXProvider components={DEFAULT_COMPONENTS}>
13+
<MDXProvider>
1414
<DocsPage
1515
{...props}
1616
product="vagrant"

‎website/layouts/vagrant-cloud.jsx

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,16 @@
11
import DocsPage from '@hashicorp/react-docs-page'
22
import order from '../data/cloud-navigation.js'
33
import { frontMatter as data } from '../pages/vagrant-cloud/**/*.mdx'
4-
import { MDXProvider } from '@mdx-js/react'
4+
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
55
import Head from 'next/head'
66
import Link from 'next/link'
7-
import Button from '@hashicorp/react-button'
8-
import Tabs, { Tab } from '../components/tabs'
97

10-
const DEFAULT_COMPONENTS = { Button, Tabs, Tab }
8+
const MDXProvider = createMdxProvider({ product: 'vagrant' })
119

1210
function CloudLayoutWrapper(pageMeta) {
1311
function CloudLayout(props) {
1412
return (
15-
<MDXProvider components={DEFAULT_COMPONENTS}>
13+
<MDXProvider>
1614
<DocsPage
1715
{...props}
1816
product="vagrant"

‎website/layouts/vmware.jsx

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
11
import DocsPage from '@hashicorp/react-docs-page'
22
import order from '../data/vmware-navigation.js'
33
import { frontMatter as data } from '../pages/vmware/**/*.mdx'
4-
import { MDXProvider } from '@mdx-js/react'
4+
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
55
import Head from 'next/head'
66
import Link from 'next/link'
7-
import Button from '@hashicorp/react-button'
87

9-
const DEFAULT_COMPONENTS = { Button }
8+
const MDXProvider = createMdxProvider({ product: 'vagrant' })
109

1110
function VMWareLayoutWrapper(pageMeta) {
1211
function VMWareLayout(props) {
1312
return (
14-
<MDXProvider components={DEFAULT_COMPONENTS}>
13+
<MDXProvider>
1514
<DocsPage
1615
{...props}
1716
product="vagrant"

0 commit comments

Comments
 (0)