From d08aa6f6b044bc1f3bd00b4a6fcc6e5d42dd49b8 Mon Sep 17 00:00:00 2001 From: Zachary Shilton <4624598+zchsh@users.noreply.github.com> Date: Wed, 21 Apr 2021 15:35:52 -0400 Subject: [PATCH] website: update readme (#10931) * website: bump to nextjs-scripts prerelease * website: update stale sections in readme * website: bump nextjs-scripts to latest prerelease * website: update docs-sidebar section to prep for shared section * website: update readme with latest blocks * website: revert bump to nextjs-scripts, deferred * website: bump to latest nextjs-scripts --- website/README.md | 30 ++++++++++----------- website/package-lock.json | 55 ++++++++++++++++++++++++++++++++------- website/package.json | 2 +- 3 files changed, 61 insertions(+), 26 deletions(-) diff --git a/website/README.md b/website/README.md index 3901d3487..de0bc163d 100644 --- a/website/README.md +++ b/website/README.md @@ -67,9 +67,11 @@ If you pull down new code from github, you should run `npm install` again. Other ## Editing Markdown Content -Documentation content is written in [Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files listed under the `/pages` directory. +Documentation content is written in [Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files listed under the `/content` directory. -To create a new page with Markdown, create a file ending in `.mdx` in the `pages/` directory. The path in the pages directory will be the URL route. For example, `pages/hello/world.mdx` will be served from the `/hello/world` URL. +To create a new page with Markdown, create a file ending in `.mdx` in a `content/`. The path in the content directory will be the URL route. For example, `content/docs/hello.mdx` will be served from the `/docs/hello` URL. + +> **Important**: Files and directories will only be rendered and published to the website if they are [included in sidebar data](#editing-navigation-sidebars). Any file not included in sidebar data will not be rendered or published. This file can be standard Markdown and also supports [YAML frontmatter](https://middlemanapp.com/basics/frontmatter/). YAML frontmatter is optional, there are defaults for all keys. @@ -86,7 +88,7 @@ The significant keys in the YAML frontmatter are: - `title` `(string)` - This is the title of the page that will be set in the HTML title. - `description` `(string)` - This is a description of the page that will be set in the HTML description. -> ⚠️ Since `api` is a reserved directory within NextJS, all `/api/**` pages are listed under the `/pages/api-docs` path. +> ⚠️ If there is a need for a `/api/*` url on this website, the url will be changed to `/api-docs/*`, as the `api` folder is reserved by next.js. ### Creating New Pages @@ -97,7 +99,7 @@ There is currently a small bug with new page creation - if you create a new page There are several custom markdown plugins that are available by default that enhance [standard markdown](https://commonmark.org/) to fit our use cases. This set of plugins introduces a couple instances of custom syntax, and a couple specific pitfalls that are not present by default with markdown, detailed below: - If you see the symbols `~>`, `->`, `=>`, or `!>`, these represent [custom alerts](https://github.com/hashicorp/remark-plugins/tree/master/plugins/paragraph-custom-alerts#paragraph-custom-alerts). These render as colored boxes to draw the user's attention to some type of aside. -- If you see `@include '/some/path.mdx'`, this is a [markdown include](https://github.com/hashicorp/remark-plugins/tree/master/plugins/include-markdown#include-markdown-plugin). It's worth noting as well that all includes resolve from `website/pages/partials` by default, and that changes to partials will not live-reload the website. +- If you see `@include '/some/path.mdx'`, this is a [markdown include](https://github.com/hashicorp/remark-plugins/tree/master/plugins/include-markdown#include-markdown-plugin). It's worth noting as well that all includes resolve from `website/content/partials` by default, and that changes to partials will not live-reload the website. - If you see `# Headline ((#slug))`, this is an example of an [anchor link alias](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-link-aliases). It adds an extra permalink to a headline for compatibility and is removed from the output. - Due to [automatically generated permalinks](https://github.com/hashicorp/remark-plugins/tree/je.anchor-link-adjustments/plugins/anchor-links#anchor-links), any text changes to _headlines_ or _list items that begin with inline code_ can and will break existing permalinks. Be very cautious when changing either of these two text items. @@ -127,6 +129,8 @@ The `Tabs` component creates tabbed content of any type, but is often used for c ![Tabs Component](https://p176.p0.n0.cdn.getcloudapp.com/items/WnubALZ4/Screen%20Recording%202020-06-11%20at%2006.03%20PM.gif?v=1de81ea720a8cc8ade83ca64fb0b9edd) +> Please refer to the [Swingset](https://react-components.vercel.app/?component=Tabs) documention for the latest examples and API reference. + It can be used as such within a markdown file: ````mdx @@ -149,7 +153,7 @@ $ curl ... -Continued normal markdown content +Contined normal markdown content ```` The intentionally skipped line is a limitation of the mdx parser which is being actively worked on. All tabs must 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. @@ -238,16 +242,8 @@ $ terraform apply - + + ## Editing Navigation Sidebars @@ -367,6 +363,8 @@ Sometimes you may have a need to include a link that is not directly to a file w If the link provided in the `href` property is external, it will display a small icon indicating this. If it's internal, it will appear the same way as any other direct file link. + + ### Plugin Docs Plugin documentation may be located within the `packer` repository, or split out into separate `packer-plugin-` repositories. For plugin docs within the `packer` repository, the process for authoring files and managing sidebar data is identical to the process for other documentation. @@ -567,6 +565,6 @@ We support the following browsers targeting roughly the versions specified. ## Deployment -This website is hosted on Netlify and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews. +This website is hosted on Vercel and configured to automatically deploy anytime you push code to the `stable-website` branch. Any time a pull request is submitted that changes files within the `website` folder, a deployment preview will appear in the github checks which can be used to validate the way docs changes will look live. Deployments from `stable-website` will look and behave the same way as deployment previews. diff --git a/website/package-lock.json b/website/package-lock.json index 26aead5b2..386686bd9 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -10,7 +10,7 @@ "dependencies": { "@hashicorp/mktg-global-styles": "3.0.1", "@hashicorp/mktg-logos": "1.0.2", - "@hashicorp/nextjs-scripts": "18.0.0", + "@hashicorp/nextjs-scripts": "18.2.0", "@hashicorp/react-button": "5.0.0", "@hashicorp/react-docs-page": "13.1.3", "@hashicorp/react-hashi-stack-menu": "2.0.0", @@ -1642,15 +1642,15 @@ "integrity": "sha512-mZyJ3xG1YTufyDLC2vWFDfj6ppXJ8uK1z5+U/9fgcuJynet5STtEpeVsyZz3oTNcXJiCjAQzvK63T0V8npnKYQ==" }, "node_modules/@hashicorp/nextjs-scripts": { - "version": "18.0.0", - "resolved": "https://registry.npmjs.org/@hashicorp/nextjs-scripts/-/nextjs-scripts-18.0.0.tgz", - "integrity": "sha512-iTFDLNOuBp586rBtdo4lAWEu0JuHccHqWb7xcLlIvOv43SwKK+9d5jzIKj7TJdQ3frtmXCZQMRctLTHXrhDCng==", + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/@hashicorp/nextjs-scripts/-/nextjs-scripts-18.2.0.tgz", + "integrity": "sha512-sSaV8RrEqMIKSRMHDP62KrlZeVv9eu1WuXFRmdNpqc9gmGUEGVc00ySmGV7YuqwjvcGWHNgVhxRjN4vMMiRTXQ==", "dependencies": { "@bugsnag/js": "7.5.4", "@bugsnag/plugin-react": "7.5.4", "@hashicorp/react-consent-manager": "4.0.0", "@hashicorp/react-enterprise-alert": "5.0.0", - "@hashicorp/react-tabs": "5.0.0", + "@hashicorp/react-tabs": "6.0.0", "@hashicorp/remark-plugins": "3.1.1", "@mapbox/rehype-prism": "0.5.0", "@mdx-js/react": "1.6.22", @@ -1709,6 +1709,26 @@ "@hashicorp/mktg-global-styles": ">= 3" } }, + "node_modules/@hashicorp/nextjs-scripts/node_modules/@hashicorp/react-inline-svg": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@hashicorp/react-inline-svg/-/react-inline-svg-1.0.2.tgz", + "integrity": "sha512-AAFnBslSTgnEr++dTbMn3sybAqvn7myIj88ijGigF6u11eSRiV64zqEcyYLQKWTV6dF4AvYoxiYC6GSOgiM0Yw==", + "peerDependencies": { + "react": "^16.9.0" + } + }, + "node_modules/@hashicorp/nextjs-scripts/node_modules/@hashicorp/react-tabs": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@hashicorp/react-tabs/-/react-tabs-6.0.0.tgz", + "integrity": "sha512-tUMyal1QYhxgukzaS1clHmYls8J5au+79c5Ea7TY1Lpg8X+pGR6+hUATS3+nhLjt+FlYy6ySI7YQSxgrb752NA==", + "dependencies": { + "@hashicorp/react-inline-svg": "^1.0.2", + "@tippy.js/react": "^3.1.1" + }, + "peerDependencies": { + "@hashicorp/mktg-global-styles": ">=3.x" + } + }, "node_modules/@hashicorp/react-button": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/@hashicorp/react-button/-/react-button-5.0.0.tgz", @@ -23769,15 +23789,15 @@ "integrity": "sha512-mZyJ3xG1YTufyDLC2vWFDfj6ppXJ8uK1z5+U/9fgcuJynet5STtEpeVsyZz3oTNcXJiCjAQzvK63T0V8npnKYQ==" }, "@hashicorp/nextjs-scripts": { - "version": "18.0.0", - "resolved": "https://registry.npmjs.org/@hashicorp/nextjs-scripts/-/nextjs-scripts-18.0.0.tgz", - "integrity": "sha512-iTFDLNOuBp586rBtdo4lAWEu0JuHccHqWb7xcLlIvOv43SwKK+9d5jzIKj7TJdQ3frtmXCZQMRctLTHXrhDCng==", + "version": "18.2.0", + "resolved": "https://registry.npmjs.org/@hashicorp/nextjs-scripts/-/nextjs-scripts-18.2.0.tgz", + "integrity": "sha512-sSaV8RrEqMIKSRMHDP62KrlZeVv9eu1WuXFRmdNpqc9gmGUEGVc00ySmGV7YuqwjvcGWHNgVhxRjN4vMMiRTXQ==", "requires": { "@bugsnag/js": "7.5.4", "@bugsnag/plugin-react": "7.5.4", "@hashicorp/react-consent-manager": "4.0.0", "@hashicorp/react-enterprise-alert": "5.0.0", - "@hashicorp/react-tabs": "5.0.0", + "@hashicorp/react-tabs": "6.0.0", "@hashicorp/remark-plugins": "3.1.1", "@mapbox/rehype-prism": "0.5.0", "@mdx-js/react": "1.6.22", @@ -23828,6 +23848,23 @@ "typescript": "4.1.3", "unified": "9.2.0", "unist-util-visit": "2.0.3" + }, + "dependencies": { + "@hashicorp/react-inline-svg": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@hashicorp/react-inline-svg/-/react-inline-svg-1.0.2.tgz", + "integrity": "sha512-AAFnBslSTgnEr++dTbMn3sybAqvn7myIj88ijGigF6u11eSRiV64zqEcyYLQKWTV6dF4AvYoxiYC6GSOgiM0Yw==", + "requires": {} + }, + "@hashicorp/react-tabs": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@hashicorp/react-tabs/-/react-tabs-6.0.0.tgz", + "integrity": "sha512-tUMyal1QYhxgukzaS1clHmYls8J5au+79c5Ea7TY1Lpg8X+pGR6+hUATS3+nhLjt+FlYy6ySI7YQSxgrb752NA==", + "requires": { + "@hashicorp/react-inline-svg": "^1.0.2", + "@tippy.js/react": "^3.1.1" + } + } } }, "@hashicorp/react-button": { diff --git a/website/package.json b/website/package.json index f39a4c55d..15591be96 100644 --- a/website/package.json +++ b/website/package.json @@ -6,7 +6,7 @@ "dependencies": { "@hashicorp/mktg-global-styles": "3.0.1", "@hashicorp/mktg-logos": "1.0.2", - "@hashicorp/nextjs-scripts": "18.0.0", + "@hashicorp/nextjs-scripts": "18.2.0", "@hashicorp/react-button": "5.0.0", "@hashicorp/react-docs-page": "13.1.3", "@hashicorp/react-hashi-stack-menu": "2.0.0",