🌷 Docs Website Maintenance (#11696)
* update dependencies, upgrade product downloader, use new docs component provider * custom components readme docs, remove old distributed tabs component
This commit is contained in:
Jeff Escalante
GitHub
parent
aef97fa061
commit
ba721197ab
@ -116,6 +116,125 @@ There are several custom markdown plugins that are available by default that enh
|
||||
|
||||
...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.
|
||||
|
||||
### Custom Components
|
||||
|
||||
A number of custom [mdx components](https://mdxjs.com/) are available for use within any `.mdx` file. Each one is documented below:
|
||||
|
||||
#### Tabs
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
It can be used as such within a markdown file:
|
||||
|
||||
````mdx
|
||||
Normal **markdown** content.
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="CLI command">
|
||||
<!-- Intentionally skipped line.. -->
|
||||
```shell-session
|
||||
$ command ...
|
||||
```
|
||||
<!-- Intentionally skipped line.. -->
|
||||
</Tab>
|
||||
<Tab heading="API call using cURL">
|
||||
|
||||
```shell-session
|
||||
$ curl ...
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Contined normal markdown content
|
||||
````
|
||||
|
||||
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.
|
||||
|
||||
#### Enterprise Alert
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
The standalone component can be used as such in markdown files:
|
||||
|
||||
```mdx
|
||||
# Page Headline
|
||||
|
||||
<EnterpriseAlert />
|
||||
|
||||
Continued markdown content...
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```mdx
|
||||
# Page Headline
|
||||
|
||||
<EnterpriseAlert>
|
||||
My custom text here, and <a href="#">a link</a>!
|
||||
</EnterpriseAlert>
|
||||
|
||||
Continued markdown content...
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Now let's look at inline usage, here's an example:
|
||||
|
||||
|
||||
|
||||
And here's how it could be used in your markdown document:
|
||||
|
||||
```mdx
|
||||
### Some Enterprise Feature <EnterpriseAlert inline />
|
||||
|
||||
Continued markdown content...
|
||||
```
|
||||
|
||||
It's also worth noting that this component will automatically adjust to the correct product colors depending on the context.
|
||||
|
||||
#### Other Components
|
||||
|
||||
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.
|
||||
|
||||
### Syntax Highlighting
|
||||
|
||||
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:
|
||||
|
||||
````
|
||||
```
|
||||
// BAD: Code block with no language tag
|
||||
```
|
||||
|
||||
```javascript
|
||||
// GOOD: Code block with a language tag
|
||||
```
|
||||
````
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
🚫**BAD**: Using `shell`, `sh`, `bash`, or `plaintext` to represent a terminal command
|
||||
|
||||
````
|
||||
```shell
|
||||
$ terraform apply
|
||||
```
|
||||
````
|
||||
|
||||
✅**GOOD**: Using `shell-session` to represent a terminal command
|
||||
|
||||
````
|
||||
```shell-session
|
||||
$ terraform apply
|
||||
```
|
||||
````
|
||||
|
||||
<!-- END: editing-markdown -->
|
||||
|
||||
<!-- BEGIN: editing-docs-sidebars -->
|
||||
|
||||
@ -1,61 +0,0 @@
|
||||
# Tabs Component
|
||||
|
||||
> An MDX-compatible Tabs component
|
||||
|
||||
This React component renders tabbed content.
|
||||
|
||||
## Usage
|
||||
|
||||
- Use the `<Tabs>` tag in your markdown file to begin a tabbed content section.
|
||||
- Use the `<Tab>` tag with a `heading` prop to separate your markdown
|
||||
|
||||
### Important
|
||||
|
||||
A line must be skipped between the `<Tab>` and your markdown (for both above and below said markdown). [This is a limitation of MDX also pointed out by the Docusaurus folks 🔗 ](https://v2.docusaurus.io/docs/markdown-features/#multi-language-support-code-blocks)
|
||||
|
||||
### Example
|
||||
|
||||
```mdx
|
||||
<Tabs>
|
||||
<Tab heading="CLI command">
|
||||
<!-- Intentionally skipped line.. -->
|
||||
### Content
|
||||
<!-- Intentionally skipped line.. -->
|
||||
</Tab>
|
||||
<Tab heading="API call using cURL">
|
||||
|
||||
### Content
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
### Component Props
|
||||
|
||||
`<Tabs>` can be provided any arbitrary `children` so long as the `heading` prop is present the React or HTML tag used to wrap markdown, that said, we provide the `<Tab>` component to separate your tab content without rendering extra, unnecessary markup.
|
||||
|
||||
This works:
|
||||
|
||||
```mdx
|
||||
<Tabs>
|
||||
<Tab heading="CLI command">
|
||||
|
||||
### Content
|
||||
|
||||
</Tab>
|
||||
....
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
This _does not_ work:
|
||||
|
||||
```mdx
|
||||
<Tabs>
|
||||
<Tab> <!-- missing the `heading` prop to provide a tab heading -->
|
||||
|
||||
### Content
|
||||
|
||||
</Tab>
|
||||
....
|
||||
</Tabs>
|
||||
```
|
||||
@ -1,20 +0,0 @@
|
||||
import s from './style.module.css'
|
||||
import ReactTabs from '@hashicorp/react-tabs'
|
||||
|
||||
export default function Tabs({ children }) {
|
||||
return (
|
||||
<span className={s.root}>
|
||||
<ReactTabs
|
||||
items={children.map((Block) => ({
|
||||
heading: Block.props.heading,
|
||||
// eslint-disable-next-line react/display-name
|
||||
tabChildren: () => Block,
|
||||
}))}
|
||||
/>
|
||||
</span>
|
||||
)
|
||||
}
|
||||
|
||||
export function Tab({ children }) {
|
||||
return <>{children}</>
|
||||
}
|
||||
@ -1,8 +0,0 @@
|
||||
/* This is a CSS overwrite on top of the existing component styles to accommodate the Learn layout */
|
||||
.root {
|
||||
& :global(.g-grid-container),
|
||||
& > :global(.g-grid-container) {
|
||||
padding-left: 0;
|
||||
padding-right: 0;
|
||||
}
|
||||
}
|
||||
@ -1,18 +1,20 @@
|
||||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import order from '../data/docs-navigation.js'
|
||||
import { frontMatter as data } from '../pages/docs/**/*.mdx'
|
||||
import { MDXProvider } from '@mdx-js/react'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
import Tabs, { Tab } from '../components/tabs'
|
||||
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
|
||||
import Button from '@hashicorp/react-button'
|
||||
|
||||
const DEFAULT_COMPONENTS = { Tabs, Tab, Button }
|
||||
const MDXProvider = createMdxProvider({
|
||||
product: 'vagrant',
|
||||
additionalComponents: { Button },
|
||||
})
|
||||
|
||||
function DocsLayoutWrapper(pageMeta) {
|
||||
function DocsLayout(props) {
|
||||
return (
|
||||
<MDXProvider components={DEFAULT_COMPONENTS}>
|
||||
<MDXProvider>
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="vagrant"
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import order from '../data/intro-navigation.js'
|
||||
import { frontMatter as data } from '../pages/intro/**/*.mdx'
|
||||
import { MDXProvider } from '@mdx-js/react'
|
||||
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
|
||||
const DEFAULT_COMPONENTS = {}
|
||||
const MDXProvider = createMdxProvider({ product: 'vagrant' })
|
||||
|
||||
function IntroLayoutWrapper(pageMeta) {
|
||||
function IntroLayout(props) {
|
||||
return (
|
||||
<MDXProvider components={DEFAULT_COMPONENTS}>
|
||||
<MDXProvider>
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="vagrant"
|
||||
|
||||
@ -1,18 +1,16 @@
|
||||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import order from '../data/cloud-navigation.js'
|
||||
import { frontMatter as data } from '../pages/vagrant-cloud/**/*.mdx'
|
||||
import { MDXProvider } from '@mdx-js/react'
|
||||
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
import Button from '@hashicorp/react-button'
|
||||
import Tabs, { Tab } from '../components/tabs'
|
||||
|
||||
const DEFAULT_COMPONENTS = { Button, Tabs, Tab }
|
||||
const MDXProvider = createMdxProvider({ product: 'vagrant' })
|
||||
|
||||
function CloudLayoutWrapper(pageMeta) {
|
||||
function CloudLayout(props) {
|
||||
return (
|
||||
<MDXProvider components={DEFAULT_COMPONENTS}>
|
||||
<MDXProvider>
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="vagrant"
|
||||
|
||||
@ -1,17 +1,16 @@
|
||||
import DocsPage from '@hashicorp/react-docs-page'
|
||||
import order from '../data/vmware-navigation.js'
|
||||
import { frontMatter as data } from '../pages/vmware/**/*.mdx'
|
||||
import { MDXProvider } from '@mdx-js/react'
|
||||
import { createMdxProvider } from '@hashicorp/nextjs-scripts/lib/providers/docs'
|
||||
import Head from 'next/head'
|
||||
import Link from 'next/link'
|
||||
import Button from '@hashicorp/react-button'
|
||||
|
||||
const DEFAULT_COMPONENTS = { Button }
|
||||
const MDXProvider = createMdxProvider({ product: 'vagrant' })
|
||||
|
||||
function VMWareLayoutWrapper(pageMeta) {
|
||||
function VMWareLayout(props) {
|
||||
return (
|
||||
<MDXProvider components={DEFAULT_COMPONENTS}>
|
||||
<MDXProvider>
|
||||
<DocsPage
|
||||
{...props}
|
||||
product="vagrant"
|
||||
|
||||
1255
website/package-lock.json
generated
1255
website/package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -4,21 +4,19 @@
|
||||
"version": "1.0.0",
|
||||
"author": "HashiCorp",
|
||||
"dependencies": {
|
||||
"@hashicorp/nextjs-scripts": "^8.3.1",
|
||||
"@hashicorp/nextjs-scripts": "^10.0.1",
|
||||
"@hashicorp/react-button": "^2.2.0",
|
||||
"@hashicorp/react-code-block": "^1.2.7",
|
||||
"@hashicorp/react-consent-manager": "^2.1.0",
|
||||
"@hashicorp/react-content": "^3.0.0-0",
|
||||
"@hashicorp/react-docs-page": "^2.0.0",
|
||||
"@hashicorp/react-content": "3.0.0-0",
|
||||
"@hashicorp/react-docs-page": "^3.0.0",
|
||||
"@hashicorp/react-docs-sidenav": "^3.2.3",
|
||||
"@hashicorp/react-global-styles": "^4.4.0",
|
||||
"@hashicorp/react-head": "^1.0.0",
|
||||
"@hashicorp/react-head": "^1.1.1",
|
||||
"@hashicorp/react-image": "^2.0.1",
|
||||
"@hashicorp/react-mega-nav": "^4.0.1-2",
|
||||
"@hashicorp/react-product-downloader": "^3.3.1",
|
||||
"@hashicorp/react-product-downloader": "^4.0.0",
|
||||
"@hashicorp/react-section-header": "^2.0.0",
|
||||
"@hashicorp/react-subnav": "^3.2.1",
|
||||
"@hashicorp/react-tabs": "^0.4.0",
|
||||
"@hashicorp/react-subnav": "^3.2.2",
|
||||
"@hashicorp/react-vertical-text-block-list": "^2.0.1",
|
||||
"babel-plugin-import-glob-array": "^0.2.0",
|
||||
"imagemin-mozjpeg": "^9.0.0",
|
||||
|
||||
@ -5,14 +5,14 @@ import Head from 'next/head'
|
||||
import HashiHead from '@hashicorp/react-head'
|
||||
import Link from 'next/link'
|
||||
|
||||
export default function DownloadsPage({ downloadData }) {
|
||||
export default function DownloadsPage({ releaseData }) {
|
||||
return (
|
||||
<div className={s.root}>
|
||||
<HashiHead is={Head} title="Downloads | Vagrant by HashiCorp" />
|
||||
<ProductDownloader
|
||||
product="Vagrant"
|
||||
version={VERSION}
|
||||
downloads={downloadData}
|
||||
releaseData={releaseData}
|
||||
>
|
||||
<Link href="/vmware/downloads">
|
||||
<a>» Download VMWare Utility</a>
|
||||
@ -24,16 +24,8 @@ export default function DownloadsPage({ downloadData }) {
|
||||
|
||||
export async function getStaticProps() {
|
||||
return fetch(`https://releases.hashicorp.com/vagrant/${VERSION}/index.json`)
|
||||
.then((r) => r.json())
|
||||
.then((r) => {
|
||||
// TODO: restructure product-downloader to run this logic internally
|
||||
return r.builds.reduce((acc, build) => {
|
||||
if (!acc[build.os]) acc[build.os] = {}
|
||||
acc[build.os][build.arch] = build.url
|
||||
return acc
|
||||
}, {})
|
||||
})
|
||||
.then((r) => ({ props: { downloadData: r } }))
|
||||
.then((res) => res.json())
|
||||
.then((releaseData) => ({ props: { releaseData } }))
|
||||
.catch(() => {
|
||||
throw new Error(
|
||||
`--------------------------------------------------------
|
||||
|
||||
@ -12,6 +12,7 @@
|
||||
|
||||
@import '~@hashicorp/react-button/dist/style.css';
|
||||
@import '~@hashicorp/react-consent-manager/dist/style.css';
|
||||
@import '~@hashicorp/react-toggle/dist/style.css';
|
||||
@import '~@hashicorp/react-section-header/dist/style.css';
|
||||
@import '~@hashicorp/react-product-downloader/dist/style.css';
|
||||
@import '~@hashicorp/react-vertical-text-block-list/dist/style.css';
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user