chore: updates generated docs (#15784)
This commit is contained in:
Kendall Strautman
GitHub
parent
4e4e791b6a
commit
5345c5285c
|
|
@ -40,35 +40,22 @@ The website can be run locally through node.js or [Docker](https://www.docker.co
|
|||
|
||||
> **Note:** If you are using a text editor that uses a "safe write" save style such as **vim** or **goland**, this can cause issues with the live reload in development. If you turn off safe write, this should solve the problem. In vim, this can be done by running `:set backupcopy=yes`. In goland, search the settings for "safe write" and turn that setting off.
|
||||
|
||||
## Using Docker
|
||||
### With Docker
|
||||
|
||||
If you wish to run the site in a container, you can run the site locally via
|
||||
`make`.
|
||||
Running the site locally is simple. Provided you have Docker installed, clone this repo, run `make`, and then visit `http://localhost:3000`.
|
||||
|
||||
- `make website` (default, recommended)
|
||||
- This command will pull and run the latest website container.
|
||||
- This includes live reload which will load your changes as you make them.
|
||||
- `make website/local`
|
||||
- This command will run the website locally using a locally built image
|
||||
- This includes live reload which will load your changes as you make them.
|
||||
- `make website/build-local`
|
||||
- This command will build a local image of the website from `hashicorp/dev-portal.git`.
|
||||
The docker image is pre-built with all the website dependencies installed, which is what makes it so quick and simple, but also means if you need to change dependencies and test the changes within Docker, you'll need a new image. If this is something you need to do, you can run `make build-image` to generate a local Docker image with updated dependencies, then `make website-local` to use that image and preview.
|
||||
|
||||
...and then visit `http://localhost:3000`.
|
||||
### With Node
|
||||
|
||||
There's no need to re-run `make website` each time the site is run, only the
|
||||
first time. Changes to content will reflect locally on refresh.
|
||||
|
||||
## Using Node
|
||||
|
||||
Make sure your local development environment has a supported version (v14.0.0+) of [node installed](https://nodejs.org/en/). You can then run:
|
||||
If your local development environment has a supported version (v10.0.0+) of [node installed](https://nodejs.org/en/) you can run:
|
||||
|
||||
- `npm install`
|
||||
- `npm start`
|
||||
|
||||
...and then visit `http://localhost:3000`.
|
||||
|
||||
There's no need to re-run `npm install` each time the site is run, only the first time. Going forward, you can just run `npm start` to get it going.
|
||||
If you pull down new code from github, you should run `npm install` again. Otherwise, there's no need to re-run `npm install` each time the site is run, you can just run `npm start` to get it going.
|
||||
|
||||
<!-- END: local-development -->
|
||||
|
||||
|
|
@ -107,12 +94,12 @@ 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.
|
||||
- > **Warning**: We are deprecating the current [paragraph alerts](https://github.com/hashicorp/remark-plugins/tree/master/plugins/paragraph-custom-alerts#paragraph-custom-alerts), in favor of the newer [MDX Inline Alert](#inline-alerts) components. The legacy paragraph alerts are represented by the symbols `~>`, `->`, `=>`, or `!>`.
|
||||
- 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.
|
||||
|
||||
Headlines are fairly self-explanitory, but here's an example of how list items that begin with inline code look.
|
||||
Headlines are fairly self-explanatory, but here's an example of how to list items that begin with inline code look.
|
||||
|
||||
```markdown
|
||||
- this is a normal list item
|
||||
|
|
@ -132,13 +119,51 @@ There are several custom markdown plugins that are available by default that enh
|
|||
|
||||
A number of custom [mdx components](https://mdxjs.com/) are available for use within any `.mdx` file. Each one is documented below:
|
||||
|
||||
#### Inline Alerts
|
||||
|
||||
There are custom MDX components available to author alert data. [See the full documentation here](https://developer.hashicorp.com/swingset/components/mdxinlinealert). They render as colored boxes to draw the user's attention to some type of aside.
|
||||
|
||||
```mdx
|
||||
## Alert types
|
||||
|
||||
### Tip
|
||||
|
||||
<Tip>
|
||||
To provide general information to the user regarding the current context or
|
||||
relevant actions.
|
||||
</Tip>
|
||||
|
||||
### Highlight
|
||||
|
||||
<Highlight>
|
||||
To provide general or promotional information to the user prominently.
|
||||
</Highlight>
|
||||
|
||||
### Note
|
||||
|
||||
<Note>
|
||||
To help users avoid an issue. Provide guidance and actions if possible.
|
||||
</Note>
|
||||
|
||||
### Warning
|
||||
|
||||
<Warning>
|
||||
To indicate critical issues that need immediate action or help users
|
||||
understand something critical.
|
||||
</Warning>
|
||||
|
||||
## Title override prop
|
||||
|
||||
<Note title="Hashiconf 2027">To provide general information.</Note>
|
||||
```
|
||||
|
||||
#### 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:
|
||||
|
||||
|
||||
|
||||
> Please refer to the [Swingset](https://react-components.vercel.app/?component=Tabs) documention for the latest examples and API reference.
|
||||
> Please refer to the [Swingset](https://react-components.vercel.app/?component=Tabs) documentation for the latest examples and API reference.
|
||||
|
||||
It can be used as such within a markdown file:
|
||||
|
||||
|
|
@ -162,7 +187,7 @@ $ curl ...
|
|||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Contined normal markdown content
|
||||
Continued 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.
|
||||
|
|
@ -416,7 +441,7 @@ This configuration would display something like the following text on the websit
|
|||
A {{ release candidate }} for <Product> {{ v1.0.0 }} is available! The release can be <a href='https://releases.hashicorp.com/<product>/{{ 1.0.0-rc1 }}'>downloaded here</a>.
|
||||
```
|
||||
|
||||
You may customize the parameters in any way you'd like. To remove a prerelease from the website, simply delete the `prerelease` paremeter from the above component.
|
||||
You may customize the parameters in any way you'd like. To remove a prerelease from the website, simply delete the `prerelease` parameter from the above component.
|
||||
|
||||
<!-- END: releases -->
|
||||
|
||||
|
|
@ -460,7 +485,7 @@ One more example - let's say that content is being moved to an external website.
|
|||
}
|
||||
```
|
||||
|
||||
If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destnation, we need to slightly change the structure as such:
|
||||
If we no longer want the link to be in the side nav, we can simply remove it. If we do still want the link in the side nav, but pointing to an external destination, we need to slightly change the structure as such:
|
||||
|
||||
```js
|
||||
{
|
||||
|
|
@ -484,9 +509,9 @@ It's also worth noting that it is possible to do glob-based redirects, for examp
|
|||
|
||||
We support the following browsers targeting roughly the versions specified.
|
||||
|
||||
|  |  |  |  |  |
|
||||
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| **Latest** | **Latest** | **Latest** | **Latest** | **11+** |
|
||||
|  |  |  |  |  |
|
||||
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| **Latest** | **Latest** | **Latest** | **Latest** | **Latest** |
|
||||
|
||||
<!-- END: browser-support -->
|
||||
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -8,7 +8,7 @@
|
|||
"npm": ">=7.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@hashicorp/platform-cli": "^2.3.0",
|
||||
"@hashicorp/platform-cli": "^2.5.1",
|
||||
"dart-linkcheck": "2.0.15",
|
||||
"husky": "4.3.8",
|
||||
"next": "^12.3.1",
|
||||
|
|
|
|||
Loading…
Reference in New Issue