iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

improve readme with blocks, trim down dependencies

This commit is contained in:
Jeff Escalante 2020-05-29 16:37:50 -04:00
parent 184dc6cc44
commit 87f38e84ef
No known key found for this signature in database
GPG Key ID: 32D23C61AB5450DB
5 changed files with 6146 additions and 10191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

283
website/README.md
View File

@ -1,16 +1,46 @@
# Packer Website
# Packer Documentation Website
[![Netlify Status](https://img.shields.io/netlify/f7fa8963-0022-4a0e-9ccf-f5385355906b?style=flat-square)](https://app.netlify.com/sites/packer-docs-platform/deploys)
[![Netlify Status](https://img.shields.io/netlify/0b9f9a3b-9bea-4889-8ad0-9c79583cb70e?style=flat-square)](https://app.netlify.com/sites/packer-www/deploys)
This subdirectory contains the entire source for the [Packer Website](https://packer.io/). This is a [NextJS](https://nextjs.org/) project, which builds a static site from these source files.
<!--
This readme file contains several blocks of generated text, to make it easier to share common information
across documentation website readmes. To generate these blocks from their source, run `npm run generate:readme`
Any edits to the readme are welcome outside the clearly noted boundaries of the blocks. Alternately, a
block itself can be safely "forked" from the central implementation simply by removing the "BEGIN" and
"END" comments from around it.
-->
## Table of Contents
- [Contributions](#contributions-welcome)
- [Running the Site Locally](#running-the-site-locally)
- [Editing Markdown Content](#editing-markdown-content)
- [Editing Navigation Sidebars](#editing-navigation-sidebars)
- [Changing the Release Version](#changing-the-release-version)
- [Redirects](#redirects)
- [Browser Support](#browser-support)
- [Deployment](#deployment)
<!-- BEGIN: contributions -->
<!-- Generated text, do not edit directly -->
## Contributions Welcome!
If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in 🚀
<!-- END: contributions -->
<!-- BEGIN: local-development -->
<!-- Generated text, do not edit directly -->
## Running the Site Locally
The website can be run locally through node.js or Docker. If you choose to run through Docker, everything will be a little bit slower due to the additional overhead, so for frequent contributors it may be worth it to use node. Also if you are a vim user, it's also worth noting that vim's swapfile usage can cause issues for the live reload functionality. In order to avoid these issues, make sure you have run `:set backupcopy=yes` within vim.
The website can be run locally through node.js or [Docker](https://www.docker.com/get-started). If you choose to run through Docker, everything will be a little bit slower due to the additional overhead, so for frequent contributors it may be worth it to use node.
> **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.
### With Docker
@ -25,11 +55,16 @@ If your local development environment has a supported version (v10.0.0+) of [nod
- `npm install`
- `npm start`
and then visit `http://localhost:3000`.
...and then visit `http://localhost:3000`.
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.
## Editing Content
<!-- END: local-development -->
<!-- BEGIN: editing-markdown -->
<!-- Generated text, do not edit directly -->
## 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.
@ -50,73 +85,18 @@ 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.
### Editing Sidebars
The structure of the sidebars are controlled by files in the [`/data` directory](data).
- Edit [this file](data/docs-navigation.js) to change the **docs** sidebar
- Edit [this file](data/guides-navigation.js) to change the **guides** sidebar
- Edit [this file](data/intro-navigation.js) to change the **intro** sidebar
To nest sidebar items, you'll want to add a new `category` key/value accompanied by the appropriate embedded `content` values.
- `category` values will be **directory names** within the `pages` directory
- `content` values will be **file names** within their appropriately nested directory.
> ⚠️ Since `api` is a reserved directory within NextJS, all `/api/**` pages are listed under the `/pages/api-docs` path.
### Creating New Pages
There is currently a small bug with new page creation - if you create a new page and link it up via subnav data while the server is running, it will report an error saying the page was not found. This can be resolved by restarting the server.
### Changing the Release Version
To change the version of Packer displayed for download on the website, head over to `data/version.js` and change the number there. It's important to note that the version number must match a version that has been released and is live on `releases.hashicorp.com` -- if it does not, the website will be unable to fetch links to the binaries and will not compile. So this version number should be changed _only after a release_.
#### Displaying a Prerelease
If there is a prerelease of any type that should be displayed on the downloads page, this can be done by editing `pages/downloads/index.jsx`. By default, the download component might look something like this:
```jsx
<ProductDownloader
product="Packer"
version={VERSION}
downloads={downloadData}
community="/resources"
/>
```
To add a prerelease, an extra `prerelease` property can be added to the component as such:
```jsx
<ProductDownloader
product="Packer"
version={VERSION}
downloads={downloadData}
community="/resources"
prerelease={{
type: 'release candidate', // the type of prerelease: beta, release candidate, etc.
name: 'v1.0.0', // the name displayed in text on the website
version: '1.0.0-rc1', // the actual version tag that was pushed to releases.hashicorp.com
}}
/>
```
This configuration would display something like the following text on the website, emphasis added to the configurable parameters:
```
A {{ release candidate }} for Packer {{ v1.0.0 }} is available! The release can be <a href='https://releases.hashicorp.com/packer/{{ 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.
### Markdown Enhancements
There are several custom markdown plugins that are available by default that enhance standard markdown 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:
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.
- 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 `# 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.
@ -136,18 +116,159 @@ 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.
### Redirects
<!-- END: editing-markdown -->
<!-- BEGIN: editing-docs-sidebars -->
<!-- Generated text, do not edit directly -->
## Editing Navigation Sidebars
The structure of the sidebars are controlled by files in the [`/data` directory](data). For example, [this file](data/docs-navigation.js) controls the **docs** sidebar. Within the `data` folder, any file with `-navigation` after it controls the navigation for the given section.
The sidebar uses a simple recursive data structure to represent _files_ and _directories_. A file is represented by a string, and a directory is represented by an object. The sidebar is meant to reflect the structure of the docs within the filesystem while also allowing custom ordering. Let's look at an example. First, here's our example folder structure:
```text
.
├── docs
│   └── directory
│   ├── index.mdx
│   ├── file.mdx
│   ├── another-file.mdx
│   └── nested-directory
│   ├── index.mdx
│   └── nested-file.mdx
```
Here's how this folder structure could be represented as a sidebar navigation, in this example it would be the file `website/data/docs-navigation.js`:
```js
export default {
category: 'directory',
content: [
'file',
'another-file',
{
category: 'nested-directory',
content: ['nested-file'],
},
],
}
```
- `category` values will be **directory names** within the `pages/<section>` directory
- `content` values will be **file names** within their appropriately nested directory
A couple more important notes:
- Within this data structure, ordering does not matter, but hierarchy does. So while you could put `file` and `another-file` in any order, or even leave one or both of them out, you could not decide to un-nest the `nested-directory` object without also un-nesting it in the filesystem.
- The `sidebar_title` frontmatter property on each `mdx` page is responsible for displaying the human-readable page name in the navigation.
- _By default_, every directory/category must have an `index.mdx` file. This file will be automatically added to the navigation as "Overview", and its `sidebar_title` property will set the human-readable name of the entire category.
Below we will discuss a couple of more unusual but still helpful patterns.
### Index-less Categories
Sometimes you may want to include a category but not have a need for an index page for the category. This can be accomplished, but a human-readable category name needs to be set manually, since the category name is normally pulled from the `sidebar_title` property of the index page. Here's an example of how an index-less category might look:
```text
.
├── docs
│   └── indexless-category
│   └── file.mdx
```
```js
// website/data/docs-navigation.js
export default {
category: 'indexless-category',
name: 'Indexless Category',
content: ['file'],
}
```
The addition of the `name` property to a category object is all it takes to be able to skip the index file.
### Custom or External Links
Sometimes you may have a need to include a link that is not directly to a file within the docs hierarchy. This can also be supported using a different pattern. For example:
```js
export default {
category: 'directory',
content: [
'file',
'another-file',
{ title: 'Tao of HashiCorp', href: 'https://www.hashicorp.com/tao-of-hashicorp' }
}
]
}
```
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 -->
<!-- BEGIN: releases -->
<!-- Generated text, do not edit directly -->
## Changing the Release Version
To change the version displayed for download on the website, head over to `data/version.js` and change the number there. It's important to note that the version number must match a version that has been released and is live on `releases.hashicorp.com` -- if it does not, the website will be unable to fetch links to the binaries and will not compile. So this version number should be changed _only after a release_.
### Displaying a Prerelease
If there is a prerelease of any type that should be displayed on the downloads page, this can be done by editing `pages/downloads/index.jsx`. By default, the download component might look something like this:
```jsx
<ProductDownloader
product="<Product>"
version={VERSION}
downloads={downloadData}
community="/resources"
/>
```
To add a prerelease, an extra `prerelease` property can be added to the component as such:
```jsx
<ProductDownloader
product="<Product>"
version={VERSION}
downloads={downloadData}
community="/resources"
prerelease={{
type: 'release candidate', // the type of prerelease: beta, release candidate, etc.
name: 'v1.0.0', // the name displayed in text on the website
version: '1.0.0-rc1', // the actual version tag that was pushed to releases.hashicorp.com
}}
/>
```
This configuration would display something like the following text on the website, emphasis added to the configurable parameters:
```
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.
<!-- END: releases -->
<!-- BEGIN: redirects -->
<!-- Generated text, do not edit directly -->
## Redirects
This website structures URLs based on the filesystem layout. This means that if a file is moved, removed, or a folder is re-organized, links will break. If a path change is necessary, it can be mitigated using redirects.
To add a redirect, head over to the `_redirects` file - the format is fairly simple. On the left is the current path, and on the right is the path that should be redirected to. It's important to note that if there are links to a `.html` version of a page, that must also be explicitly redirected. For example:
```
/foo /bar
/foo.html /bar
/foo /bar 301!
/foo.html /bar 301!
```
This redirect rule will send all incoming links to `/foo` and `/foo.html` to `/bar`. For more details on the redirects file format, [check out the docs on netlify](https://docs.netlify.com/routing/redirects/rewrites-proxies).
This redirect rule will send all incoming links to `/foo` and `/foo.html` to `/bar`. For more details on the redirects file format, [check out the docs on netlify](https://docs.netlify.com/routing/redirects/rewrites-proxies). Note that it is critical that `301!` is added to every one-to-one redirect - if it is left off the redirect may not work.
There are a couple important caveats with redirects. First, redirects are applied at the hosting layer, and therefore will not work by default in local dev mode. To test in local dev mode, you can use [`netlify dev`](https://www.netlify.com/products/dev/), or just push a commit and check using the deploy preview.
@ -156,8 +277,8 @@ Second, redirects do not apply to client-side navigation. By default, all links
Let's look at an example. Say you have a page called `/docs/foo` which needs to be moved to `/docs/nested/foo`. Additionally, this is a page that has been around for a while and we know there are links into `/docs/foo.html` left over from our previous website structure. First, we move the page, then adjust the docs sidenav, in `data/docs-navigation.js`. Find the category the page is in, and move it into the appropriate subcategory. Next, we add to `_redirects` as such:
```
/foo /nested/foo
/foo.html /nested/foo
/foo /nested/foo 301!
/foo.html /nested/foo 301!
```
Finally, we run a global search for internal links to `/foo`, and make sure to adjust them to be `/nested/foo` - this is to ensure that client-side navigation still works correctly. _Adding a redirect alone is not enough_.
@ -179,7 +300,7 @@ If we no longer want the link to be in the side nav, we can simply remove it. If
{
category: 'docs',
content: [
{ title: 'Foo Title', href: 'https://learn.hashicorp.com/vault/foo' }
{ title: 'Foo Title', href: 'https://learn.hashicorp.com/<product>/foo' }
]
}
```
@ -188,6 +309,26 @@ As the majority of items in the side nav are internal links, the structure makes
It's also worth noting that it is possible to do glob-based redirects, for example matching `/docs/*`, and you may see this pattern in the `_redirects` file. This type of redirect is much higher risk and the behavior is a bit more nuanced, so if you need to add a glob redirect, please reach out to the website maintainers and ask about it first.
### Deployment
<!-- END: redirects -->
<!-- BEGIN: browser-support -->
<!-- Generated text, do not edit directly -->
## Browser Support
We support the following browsers targeting roughly the versions specified.
| ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_24x24.png) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_24x24.png) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/master/src/opera/opera_24x24.png) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_24x24.png) | ![Internet Explorer](https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_24x24.png) |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Latest** | **Latest** | **Latest** | **Latest** | **11+** |
<!-- END: browser-support -->
<!-- BEGIN: deployment -->
<!-- Generated text, do not edit directly -->
## 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.
<!-- END: deployment -->

15997
website/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

50
website/package.json
View File

@ -1,49 +1,28 @@
{
"name": "packer-docs",
"description": "Description of your website",
"version": "0.0.1",
"description": "Documentation website for HashiCorp Packer",
"version": "1.0.0",
"author": "HashiCorp",
"dependencies": {
"@bugsnag/js": "^7.0.0",
"@bugsnag/plugin-react": "^7.0.0",
"@hashicorp/nextjs-scripts": "^6.2.0-9",
"@hashicorp/react-alert": "^2.0.0",
"@hashicorp/react-button": "^2.1.8",
"@hashicorp/react-consent-manager": "^2.0.8",
"@hashicorp/nextjs-scripts": "^8.3.1",
"@hashicorp/react-button": "^2.2.0",
"@hashicorp/react-content": "^3.0.0-0",
"@hashicorp/react-docs-page": "^1.3.1",
"@hashicorp/react-docs-page": "^2.0.0",
"@hashicorp/react-docs-sidenav": "^3.2.3",
"@hashicorp/react-docs-sitemap": "^1.0.0",
"@hashicorp/react-footer": "^3.1.13",
"@hashicorp/react-global-styles": "^4.1.0",
"@hashicorp/react-head": "^0.1.1",
"@hashicorp/react-hero": "^3.0.6",
"@hashicorp/react-image": "^2.0.1",
"@hashicorp/react-inline-svg": "^1.0.0",
"@hashicorp/react-global-styles": "^4.4.0",
"@hashicorp/react-head": "^1.0.0",
"@hashicorp/react-mega-nav": "^4.0.1-2",
"@hashicorp/react-product-downloader": "^3.1.1",
"@hashicorp/react-product-downloader": "^3.3.0",
"@hashicorp/react-section-header": "^2.0.0",
"@hashicorp/react-subnav": "^3.1.0",
"@hashicorp/react-text-and-content": "^4.0.8",
"@hashicorp/react-text-split": "^0.2.5",
"@hashicorp/react-text-split-with-code": "0.0.8",
"@hashicorp/react-text-split-with-image": "^1.2.5",
"@hashicorp/react-subnav": "^3.2.1",
"@hashicorp/react-vertical-text-block-list": "^2.0.1",
"babel-plugin-import-glob-array": "^0.2.0",
"highlight.js": "^10.0.0",
"imagemin-mozjpeg": "^8.0.0",
"imagemin-optipng": "^7.1.0",
"imagemin-svgo": "^7.1.0",
"isomorphic-unfetch": "^3.0.0",
"marked": "^0.7.0",
"next": "9.3.5",
"nprogress": "^0.2.0",
"nuka-carousel": "^4.6.7",
"imagemin-mozjpeg": "^9.0.0",
"imagemin-optipng": "^8.0.0",
"imagemin-svgo": "^8.0.0",
"next": "9.4.4",
"react": "^16.13.1",
"react-device-detect": "^1.11.14",
"react-dom": "^16.13.1",
"slugify": "^1.4.0",
"stringify-object": "^3.3.0"
"react-dom": "^16.13.1"
},
"devDependencies": {
"dart-linkcheck": "^2.0.15",
@ -64,6 +43,7 @@
"export": "node --max-old-space-size=2048 ./node_modules/.bin/next export",
"format": "next-hashicorp format",
"generate:component": "next-hashicorp generate component",
"generate:readme": "next-hashicorp markdown-blocks README.md",
"lint": "next-hashicorp lint",
"start": "rm -rf .next/cache/next-babel-loader/ && next dev",
"static": "npm run build && npm run export && cp _redirects out/.",

5
website/pages/style.css
View File

@ -15,7 +15,6 @@
@import '~@hashicorp/react-button/dist/style.css';
@import '~@hashicorp/react-consent-manager/dist/style.css';
@import '~@hashicorp/react-checkbox-input/dist/style.css';
@import '~@hashicorp/react-hero/dist/style.css';
@import '~@hashicorp/react-section-header/dist/style.css';
@import '~@hashicorp/react-logo-grid/dist/style.css';
@import '~@hashicorp/react-product-downloader/dist/style.css';
@ -23,11 +22,7 @@
@import '~@hashicorp/react-docs-sidenav/dist/style.css';
@import '~@hashicorp/react-content/dist/style.css';
@import '~@hashicorp/react-subnav/dist/style.css';
@import '~@hashicorp/react-text-and-content/dist/style.css';
@import '~@hashicorp/react-consent-manager/dist/style.css';
@import '~@hashicorp/react-alert/dist/style.css';
@import '~@hashicorp/react-text-split/dist/style.css';
@import '~@hashicorp/react-text-split-with-code/dist/style.css';
@import '~@hashicorp/react-mega-nav/style.css';
@import '~@hashicorp/react-docs-page/style.css';

2
website/prettier.config.js
View File

@ -1,3 +1,3 @@
module.exports = {
...require('@hashicorp/nextjs-scripts/prettier.config.js')
...require('@hashicorp/nextjs-scripts/prettier.config.js'),
}