From ba721197ab8c2982ad9ca1499a7d250b2471b458 Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Thu, 11 Jun 2020 19:21:38 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=B7=20Docs=20Website=20Maintenance=20(?= =?UTF-8?q?#11696)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * update dependencies, upgrade product downloader, use new docs component provider * custom components readme docs, remove old distributed tabs component --- website/README.md | 119 ++ website/components/tabs/README.md | 61 -- website/components/tabs/index.jsx | 20 - website/components/tabs/style.module.css | 8 - website/layouts/docs.jsx | 10 +- website/layouts/intro.jsx | 6 +- website/layouts/vagrant-cloud.jsx | 8 +- website/layouts/vmware.jsx | 7 +- website/package-lock.json | 1255 +++++++++++----------- website/package.json | 14 +- website/pages/downloads/index.jsx | 16 +- website/pages/style.css | 1 + 12 files changed, 765 insertions(+), 760 deletions(-) delete mode 100644 website/components/tabs/README.md delete mode 100644 website/components/tabs/index.jsx delete mode 100644 website/components/tabs/style.module.css diff --git a/website/README.md b/website/README.md index 7d65e3039..27f6c87e4 100644 --- a/website/README.md +++ b/website/README.md @@ -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: + +![Tabs Component](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALZ4/Screen%20Recording%202020-06-11%20at%2006.03%20PM.gif?v=1de81ea720a8cc8ade83ca64fb0b9edd) + +It can be used as such within a markdown file: + +````mdx +Normal **markdown** content. + + + + +```shell-session +$ command ... +``` + + + + +```shell-session +$ curl ... +``` + + + + +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: + +![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) + +The standalone component can be used as such in markdown files: + +```mdx +# Page Headline + + + +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 + + + My custom text here, and a link! + + +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: + +![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) + +And here's how it could be used in your markdown document: + +```mdx +### Some Enterprise Feature + +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 +``` +```` + diff --git a/website/components/tabs/README.md b/website/components/tabs/README.md deleted file mode 100644 index bdf31a710..000000000 --- a/website/components/tabs/README.md +++ /dev/null @@ -1,61 +0,0 @@ -# Tabs Component - -> An MDX-compatible Tabs component - -This React component renders tabbed content. - -## Usage - -- Use the `` tag in your markdown file to begin a tabbed content section. -- Use the `` tag with a `heading` prop to separate your markdown - -### Important - -A line must be skipped between the `` 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 - - - -### Content - - - - -### Content - - - -``` - -### Component Props - -`` 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 `` component to separate your tab content without rendering extra, unnecessary markup. - -This works: - -```mdx - - - -### Content - - -.... - -``` - -This _does not_ work: - -```mdx - - - -### Content - - -.... - -``` diff --git a/website/components/tabs/index.jsx b/website/components/tabs/index.jsx deleted file mode 100644 index b6fa65e67..000000000 --- a/website/components/tabs/index.jsx +++ /dev/null @@ -1,20 +0,0 @@ -import s from './style.module.css' -import ReactTabs from '@hashicorp/react-tabs' - -export default function Tabs({ children }) { - return ( - - ({ - heading: Block.props.heading, - // eslint-disable-next-line react/display-name - tabChildren: () => Block, - }))} - /> - - ) -} - -export function Tab({ children }) { - return <>{children} -} diff --git a/website/components/tabs/style.module.css b/website/components/tabs/style.module.css deleted file mode 100644 index 385160113..000000000 --- a/website/components/tabs/style.module.css +++ /dev/null @@ -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; - } -} diff --git a/website/layouts/docs.jsx b/website/layouts/docs.jsx index e46a959f7..6b25bf094 100644 --- a/website/layouts/docs.jsx +++ b/website/layouts/docs.jsx @@ -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 ( - + + + + » Download VMWare Utility @@ -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( `-------------------------------------------------------- diff --git a/website/pages/style.css b/website/pages/style.css index c951700a2..25fc9ee29 100644 --- a/website/pages/style.css +++ b/website/pages/style.css @@ -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';