Add TOC functionality (#2527)

* add jekyll-toc plugin

* add jekyll-toc to plugins lost

* update layouts to include TOC

* enable TOC for relational database page

* add bundle install to npm run start command

* update TOC styles

* add header for table of contents

* update styles

* build jekyll with --incremental flag locally

* update CLI download links

* remove incremental flag

* enable TOC by default

* reorganize doc

* update heading structure

* update TOC to only top level headers

* update header levels for table of contents

* adjust styles

* styling refactor

* render TOC conditionally

* fix TOC to hide on pages where TOC is empty

* fix headers on various pages so that TOC renders as expected and page is easily navigable

* fix bad links

Gemfile

@@ -31,3 +31,5 @@ gem "wdm", "~> 0.1.0" if Gem.win_platform?
 gem "html-proofer", "~> 3.10"
 
 gem "addressable", ">= 2.8.0"
+
+gem 'jekyll-toc'

Gemfile.lock

@@ -58,6 +58,9 @@ GEM
       jekyll (>= 3.8, < 5.0)
     jekyll-sitemap (1.4.0)
       jekyll (>= 3.7, < 5.0)
+    jekyll-toc (0.19.0)
+      jekyll (>= 3.9)
+      nokogiri (~> 1.12)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     kramdown (2.4.0)
@@ -120,6 +123,7 @@ DEPENDENCIES
   jekyll-redirect-from
   jekyll-seo-tag
   jekyll-sitemap
+  jekyll-toc
   tzinfo-data
 
 RUBY VERSION

_assets/css/styles.scss

@@ -683,4 +683,18 @@ blockquote .source {
 }
 .highlight .ss {
   color: #90a959;
-}
+}
+
+#table-of-contents {
+  @include u-border($theme-color-base-lighter);
+  border-width: 1px;
+  border-style: solid;
+  padding: 0 2em;
+  background-color: color($theme-color-accent-warm-light);
+}
+
+#table-of-contents ol {
+  font-size: .9rem;
+  padding: 0;
+  list-style-position: inside;
+}

_config.yml

@@ -179,6 +179,7 @@ plugins:
   - jekyll-sitemap
   - jekyll-seo-tag
   - jekyll-last-modified-at
+  - jekyll-toc
 
 ############################################################
 # Site configuration for the Jekyll 3 Pagination Gem
@@ -248,3 +249,52 @@ feed:
 
 include:
   - .well-known
+
+defaults:
+  - scope:
+      path: "_docs/compliance"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/deployment"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/getting-started"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/management"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/orgs-spaces"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/overview"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/pricing"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/services"
+    values:
+      toc: true
+  - scope:
+      path: "_docs/technology"
+    values:
+      toc: true
+
+toc:
+  min_level: 2
+  max_level: 2
+  ordered_list: true
+  no_toc_section_class: no_toc_section
+  list_id: toc
+  list_class: section-nav
+  sublist_class: ''
+  item_class: toc-entry
+  item_prefix: toc-

_docs/compliance/cisa-directives.md

@@ -2,11 +2,9 @@
 parent: compliance
 layout: docs
 sidenav: true
-title: CISA Directives
+title: CISA Emergency Directives
 ---
 
-# CISA Emergency Directives
-
 The Cybersecurity and Infrastructure Security Agency (CISA) periodically issues “[Emergency Directives](https://cyber.dhs.gov/directives/),” which require action by cloud.gov, as a FedRAMP-authorized service.
 
 In response to CISA Emergency Directives, cloud.gov will:
@@ -17,68 +15,67 @@ In response to CISA Emergency Directives, cloud.gov will:
 
 We will no longer be publicly providing our specific compliance status, as future directives could apply to components in the cloud.gov system.
 
-# FY2022
+## FY2022
 
-## CISA Emergency Directive 22-03, “Mitigate VMware Vulnerabilities.”
+### CISA Emergency Directive 22-03, “Mitigate VMware Vulnerabilities.”
 
 In response to CISA Emergency Directive 22-03, “Mitigate VMware Vulnerabilities”
 (https://www.cisa.gov/emergency-directive-22-03)
 cloud.gov has provided required applicability information in our FedRAMP secure repository: https://community.max.gov/x/mjypgg. Customers can use the FedRAMP repository, or open a cloud.gov support request.
 
-## CISA Emergency Directive 22-02, “Mitigate log4j Vulnerability”
+### CISA Emergency Directive 22-02, “Mitigate log4j Vulnerability”
 
 Please see our page, [Log4J Vulnerability / ED 22-02 Update](https://cloud.gov/2021/12/22/log4j_vulnerability_bod_22-02_update/).
 
-# FY2021
+## FY2021
 
-## CISA Emergency Directive 21-04: Windows Print Spooler
+### CISA Emergency Directive 21-04: Windows Print Spooler
 
 In response to CISA Emergency Directive 21-04, “Mitigate Windows Print Spooler Service Vulnerability” (https://cyber.dhs.gov/ed/21-04/), cloud.gov has provided required applicability information in our FedRAMP secure repository: https://community.max.gov/x/mjypgg
 
 We do not publicly provide specific directive compliance status. Authorized customers can access our FedRAMP package as described at https://cloud.gov/docs/overview/fedramp-tracker/#start-the-ato-process
 
-## CISA Emergency Directive 21-03 for Pulse Connect Secure: Not impacted
+### CISA Emergency Directive 21-03 for Pulse Connect Secure: Not impacted
 
 Cloud.gov has NO instances of Pulse Connect Secure
 
-On April 20, 2021, the DHS Cybersecurity and Infrastructure Security Agency 
-(CISA) published Emergency Directive 21-03: "Mitigate Pulse Connect Secure Product Vulnerabilities" 
+On April 20, 2021, the DHS Cybersecurity and Infrastructure Security Agency
+(CISA) published Emergency Directive 21-03: "Mitigate Pulse Connect Secure Product Vulnerabilities"
 ([https://cyber.dhs.gov/ed/21-03/](https://cyber.dhs.gov/ed/21-03/))
 
 Status: The cloud.gov system has no instances of Pulse Connect Secure. We are fully compliant with ED-21-03.
 
-## CISA Emergency Directive 21-02 for Microsoft Exchange: Not impacted
+### CISA Emergency Directive 21-02 for Microsoft Exchange: Not impacted
 
 cloud.gov has NO instances of Microsoft Exchange on-premises.
 
-On March 3, 2021, the DHS Cybersecurity and Infrastructure Security Agency 
-(CISA) published Emergency Directive 21-02: "Mitigate Microsoft Exchange On-Premises Product Vulnerabilities" 
+On March 3, 2021, the DHS Cybersecurity and Infrastructure Security Agency
+(CISA) published Emergency Directive 21-02: "Mitigate Microsoft Exchange On-Premises Product Vulnerabilities"
 ([https://cyber.dhs.gov/ed/21-02/](https://cyber.dhs.gov/ed/21-02/))
 
-
 Status: The cloud.gov system has no instances of Microsoft Exchange on-premises. We are fully compliant with ED-21-02.
 
-## CISA Emergency Directive 21-01: Mitigate SolarWinds Orion Code Compromise: Not impacted
+### CISA Emergency Directive 21-01: Mitigate SolarWinds Orion Code Compromise: Not impacted
 
 On December 13, 2020, the DHS Cybersecurity and Infrastructure Security Agency (CISA) published [Emergency Directive 21-01, “Mitigate SolarWinds Orion Code Compromise”](https://cyber.dhs.gov/ed/21-01/).
 
 We want to assure cloud.gov customers that the SolarWinds Orion code compromise is not applicable to cloud.gov. There are no SolarWinds components in the cloud.gov system.
 
-# FY2020
+## FY2020
 
-## CISA Directive 20-04 for Netlogon Elevation of Privilege: cloud.gov is fully compliant
+### CISA Directive 20-04 for Netlogon Elevation of Privilege: cloud.gov is fully compliant
 
 On September 18, 2020, the DHS Cybersecurity and Infrastructure Security Agency (CISA) published Emergency Directive 20-04, [Mitigate Netlogon Elevation of Privilege Vulnerability from August 2020 Patch Tuesday](https://cyber.dhs.gov/ed/20-04/).
 
 The FedRAMP PMO requested that cloud.gov (and all CSPs) notify agency customers on our compliance status with the directive, which is that **cloud.gov has zero systems impacted by this vulnerability**.
 
-## CISA Directive 20-03 for Windows DNS: cloud.gov is fully compliant
+### CISA Directive 20-03 for Windows DNS: cloud.gov is fully compliant
 
 On July 16, 2020, the DHS Cybersecurity and Infrastructure Security Agency (CISA) published Emergency Directive 20-03, [Mitigate Windows DNS Server Vulnerability from July 2020 Patch Tuesday](https://cyber.dhs.gov/ed/20-03/).
 
 The FedRAMP PMO requested that cloud.gov (and all CSPs) notify agency customers on our compliance status with the directive, which is that **cloud.gov has zero systems impacted by this vulnerability**.
 
-## CISA Directive 20-02: Mitigate Windows Vulnerabilities
+### CISA Directive 20-02: Mitigate Windows Vulnerabilities
 
 On January 15, 2020, the FedRAMP program office directed all authorized cloud service providers to comply with Department of Homeland Security (DHS) Cybersecurity and Infrastructure Security Agency (CISA) Emergency Directive 20-02, [Mitigate Windows Vulnerabilities from January 2020 Patch Tuesday](https://cyber.dhs.gov/ed/20-02/)
 

_docs/compliance/meeting-tic-requirements.md

@@ -27,7 +27,7 @@ If you need agency user or developer traffic to traverse a TIC
 point, then some of the architectural guidance related to TIC 2.2
 is provided below.
 
-### Restricting developer and operator access to cloud.gov services
+## Restricting developer and operator access to cloud.gov services
 
 You can ensure that developer and operator access to cloud.gov
 services traverses your agency's TIC so that you can monitor all
@@ -70,7 +70,7 @@ cloud.gov's TLS endpoint is not restricted, but rather accessible over the open
 
 Your agency can accomplish this by establishing an operational requirement that all administrative access to cloud.gov services happens via the agency network. You can further enforce this requirement with a technical control: Prevent users in your domain from using the cloud.gov API except from your agency's TIC egress range. Requests from an IP origin that does not match the range we have on record for your TIC (the dotted/dashed line in the diagram) will be rejected.
 
-### Restricting usage of your application
+## Restricting usage of your application
 
 You may also need to restrict access through the "front door" of your deployed applications, such as administrator access to a Wordpress site, or public access to an internal-only service. The diagram below shows where you can implement this restriction.
 

_docs/deployment/assets.md

@@ -2,14 +2,14 @@
 parent: deployment
 layout: docs
 sidenav: true
-redirect_from: 
+redirect_from:
     - /docs/apps/assets/
 title: Building static assets
 ---
 
 Applications with non-trivial static assets (Javascript and CSS files) often include a build step to bundle and minify files.
 
-### Build assets on CI
+## Build assets on CI
 
 For applications [deployed from a continuous integration service]({{ site.baseurl }}{% link _docs/management/continuous-deployment.md %}), building assets on CI is a natural fit. Before deploying to cloud.gov, the CI service runs the asset build process. Then the compiled assets are pushed to cloud.gov along with the application code. Here's a minimal example for Travis CI:
 
@@ -35,7 +35,7 @@ Examples in the wild:
 
 * [eRegulations: Notice & Comment](https://github.com/eregs/notice-and-comment)
 
-### Build assets on cloud.gov
+## Build assets on cloud.gov
 
 If the application and build process are implemented in the same language, assets can be built directly on cloud.gov on application start. Here's a minimal example for a node.js application:
 

_docs/deployment/docker.md

@@ -33,30 +33,31 @@ Here are some considerations to keep in mind when deciding to use Docker images
 
 <!-- Based on the table in this slide: https://twitter.com/benbravo73/status/781125385777999872 -->
 
-### Runtime differences
+## Runtime differences
 
 Pushing an application using a Docker image creates the same type of container in the same runtime as using a buildpack does. When you supply a Docker image for your application, Cloud Foundry:
+
 1. fetches the Docker image
-1. uses the image layers to construct a base filesystem 
+1. uses the image layers to construct a base filesystem
 1. uses the image metadata to determine the command to run, environment vars, user id, and port to expose (if any)
-1. creates an app specification based on the steps above 
+1. creates an app specification based on the steps above
 1. passes the app specification on to diego (the multi-host container management system) to be run as a linux container.
 
 No Docker components are involved in this process - your applications are run under the `garden-runc` runtime (versus `containerd` in Docker). Both `garden-runc` and `containerd` are layers built on top of the Open Container Initiative's `runc` package. They have significant overlap in the types of problems they solve and in many of the ways they try to solve them.
 For example, both `garden-runc` and `containerd`:
+
 - use cgroups to limit resource usage
 - use process namespaces to isolate processes
 - combine image layers into a single root filesystem
 - use user namespaces to prevent users with escalated privileges in containers from gaining escalated privileges on hosts (this is an available option on `containerd` and is a default on `garden-runc`)
 
 Additionally, since containers are running in Cloud Foundry, most or all of the other components of the Docker ecosystem are are replaced with Cloud Foundry components, such as service discovery, process monitoring, virtual networking, routing, volumes, etc. This means most Docker-specific guidance, checklists, etc., will not be directly applicable for applications within Cloud Foundry, regardless of whether they're pushed as Docker images or buildpack applications.
 
-
-#### Docker as tasks
+### Docker as tasks
 
 There is [a Cloud Foundry API for tasks creation](http://v3-apidocs.cloudfoundry.org/version/3.31.0/index.html#tasks). This allows single, one-off tasks to be triggered through the API.
 
-### Using non-standard ports in Docker containers
+## Using non-standard ports in Docker containers
 
 When you assign a route to an app running on cloud.gov using the `*.app.cloud.gov` domain, external ports 80 and 443 are mapped to a dynamically assigned internal port on the container(s) running your app. You can't change the internal port assigned to your app if it's been assigned an `*.app.cloud.gov` domain, but you can use alternate ports if your app is assigned [an internal route](https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html#internal-routes) on cloud.gov.
 
@@ -68,19 +69,21 @@ In this scenario, if you want to enable external traffic to reach your Docker ap
 
 * Enable container-to-container traffic by [adding a new network policy](https://cli.cloudfoundry.org/en-US/v6/add-network-policy.html) specifying the source app (your nginx proxy) and the destination app (your Docker app) as well as the port and protocol for the traffic.
 
-### Docker + Cloud Foundry examples
+## Docker + Cloud Foundry examples
 
-#### Spring Music
+### Spring Music
 
 We often use the [Spring Music app](https://github.com/cloudfoundry-samples/spring-music) to demonstrate the use of database services on Cloud Foundry. The same application works when bundled [into a Docker image](https://fabianlee.org/2018/05/24/docker-running-a-spring-boot-based-app-in-a-docker-container/), and works identically.
 
 For example, push it to cloud.gov using a prebuilt Docker image with an in-memory database:
-```
+
+```shell
 cf push my-spring --docker-image pburkholder/my-springmusic -m 1016M
 ```
 
 Then create a database service, bind it, and restage the app to use the database:
-```
+
+```shell
 cf create-service aws-rds micro-psql my-spring-db
 cf bind-service my-spring my-spring-db
 cf restage my-spring