github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/README.md (about)

     1  # Nomad Website
     2  
     3  [![Netlify Status](https://img.shields.io/netlify/57d01198-7abc-4c39-a89b-386a2fe7de09?style=flat-square)](https://app.netlify.com/sites/nomad-website/deploys)
     4  
     5  This subdirectory contains the entire source for the [Nomad Website](https://nomadproject.io/). This is a [NextJS](https://nextjs.org/) project, which builds a static site from these source files.
     6  
     7  ## Contributions Welcome!
     8  
     9  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 🚀
    10  
    11  ## Running the Site Locally
    12  
    13  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.
    14  
    15  ### With Docker
    16  
    17  Running the site locally is simple. Provided you have Docker installed, clone this repo, run `make`, and then visit `http://localhost:3000`.
    18  
    19  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.
    20  
    21  ### With Node
    22  
    23  If your local development environment has a supported version (v10.0.0+) of [node installed](https://nodejs.org/en/) you can run:
    24  
    25  - `npm install`
    26  - `npm start`
    27  
    28  and then visit `http://localhost:3000`.
    29  
    30  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.
    31  
    32  ## Editing Content
    33  
    34  Documentation content is written in [Markdown](https://www.markdownguide.org/cheat-sheet/) and you'll find all files listed under the `/pages` directory.
    35  
    36  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.
    37  
    38  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.
    39  
    40  ```yaml
    41  ---
    42  title: 'My Title'
    43  description: "A thorough, yet succinct description of the page's contents"
    44  ---
    45  
    46  ```
    47  
    48  The significant keys in the YAML frontmatter are:
    49  
    50  - `title` `(string)` - This is the title of the page that will be set in the HTML title.
    51  - `description` `(string)` - This is a description of the page that will be set in the HTML description.
    52  
    53  > ⚠️Since `api` is a reserved directory within NextJS, all `/api/**` pages are listed under the `/pages/api-docs` path.
    54  
    55  ### Editing Sidebars
    56  
    57  The structure of the sidebars are controlled by files in the [`/data` directory](data).
    58  
    59  - Edit [this file](data/docs-navigation.js) to change the **docs** sidebar
    60  - Edit [this file](data/api-navigation.js) to change the **api docs** sidebar
    61  
    62  To nest sidebar items, you'll want to add a new `category` key/value accompanied by the appropriate embedded `content` values.
    63  
    64  - `category` values will be **directory names** within the `pages` directory
    65  - `content` values will be **file names** within their appropriately nested directory.
    66  
    67  ### Creating New Pages
    68  
    69  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.
    70  
    71  ### Changing the Release Version
    72  
    73  To change the version of Nomad 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_.
    74  
    75  ### Displaying a Prerelease
    76  
    77  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:
    78  
    79  ```jsx
    80  <ProductDownloader
    81    product="Nomad"
    82    version={VERSION}
    83    downloads={downloadData}
    84    community="/resources"
    85  />
    86  ```
    87  
    88  To add a prerelease, an extra `prerelease` property can be added to the component as such:
    89  
    90  ```jsx
    91  <ProductDownloader
    92    product="Nomad"
    93    version={VERSION}
    94    downloads={downloadData}
    95    community="/resources"
    96    prerelease={{
    97      type: 'release candidate', // the type of prerelease: beta, release candidate, etc.
    98      name: 'v1.0.0', // the name displayed in text on the website
    99      version: '1.0.0-rc1' // the actual version tag that was pushed to releases.hashicorp.com
   100    }}
   101  />
   102  ```
   103  
   104  This configuration would display something like the following text on the website, emphasis added to the configurable parameters:
   105  
   106  ```
   107  A {{ release candidate }} for Nomad {{ v1.0.0 }} is available! The release can be <a href='https://releases.hashicorp.com/nomad/{{ 1.0.0-rc1 }}'>downloaded here</a>.
   108  ```
   109  
   110  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.
   111  
   112  ### Markdown Enhancements
   113  
   114  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:
   115  
   116  - 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.
   117  - 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.
   118  - 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.
   119  - 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.
   120  
   121    Headlines are fairly self-explanitory, but here's an example of how list items that begin with inline code look.
   122  
   123    ```markdown
   124    - this is a normal list item
   125    - `this` is a list item that begins with inline code
   126    ```
   127  
   128    Its worth noting that _only the inline code at the beginning of the list item_ will cause problems if changed. So if you changed the above markup to...
   129  
   130    ```markdown
   131    - lsdhfhksdjf
   132    - `this` jsdhfkdsjhkdsfjh
   133    ```
   134  
   135    ...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.
   136  
   137  ## Deployment
   138  
   139  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.