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
This commit is contained in:
Zachary Shilton
GitHub
parent
4be2c350bf
commit
d08aa6f6b0
|
|
@ -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/<subdirectory>`. 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
|
|||
|
||||
|
||||
|
||||
> 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 ...
|
|||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
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
|
|||
|
||||
<!-- END: editing-markdown -->
|
||||
|
||||
<!--
|
||||
|
||||
NOTE: The "Editing Navigation Sidebars" section is forked from editing-docs-sidebars.
|
||||
|
||||
We plan on rolling these changes back into our "readme partials" source once all docs sites
|
||||
have been transitioned to the JSON navigation format. See MKTG_032 for details:
|
||||
|
||||
https://docs.google.com/document/d/1kYvbyd6njHFSscoE1dtDNHQ3U8IzaMdcjOS0jg87rHg/
|
||||
|
||||
-->
|
||||
<!-- BEGIN: editing-docs-sidebars -->
|
||||
<!-- Generated text, do not edit directly -->
|
||||
|
||||
## 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.
|
||||
|
||||
<!-- END: editing-docs-sidebars -->
|
||||
|
||||
### 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.
|
||||
|
||||
<!-- END: deployment -->
|
||||
|
|
|
|||
|
|
@ -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": {
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
Loading…
Reference in New Issue