Merge pull request #539 from Rene2mt/feature-web-user-guides

HTML version of FedRAMP Guides for OSCAL-based Content

.gitmodules

@@ -15,4 +15,6 @@
 	url = https://github.com/schematron/schematron.git
 	branch = master
 	ignore = dirty
-
+[submodule "docs/themes/uswds"]
+	path = docs/themes/uswds
+	url = https://github.com/usnistgov/hugo-uswds.git

docs/README.md

@@ -0,0 +1,86 @@
+# FedRAMP Automation Website
+
+This subdirectory contains source code for the FedRAMP OSCAL GitHub Page (URL TBD). Below are instructions for building the site for local development if making any contributions to the documentation.
+
+The website is built using the [Hugo](https://gohugo.io/) static site generator and the [United States Web Design System](https://designsystem.digital.gov/) (USWDS).
+
+## Prerequisites
+
+If using Docker:
+
+- [Docker 20.10+](https://docs.docker.com/install/)
+
+If not using Docker:
+
+- macOS, Linux or Windows Subsystem for Linux (WSL) (model doc build scripts don't support Windows natively at this time)
+- [Hugo](https://gohugo.io/)
+
+
+## Using Hugo
+
+[Hugo](https://gohugo.io/) is a popular open source static site generator. It is a general-purpose framework that builds pages when the content is created or updated.
+
+Instructions for installing the Hugo CLI on your OS can be found [here](https://gohugo.io/getting-started/installing).
+
+The website's visual styling is also backed by the U.S. Web Design System (USWDS) via an open source Hugo theme at https://github.com/usnistgov/hugo-uswds.
+
+The USWDS framework is documented here: https://designsystem.digital.gov/.
+
+### Building the site with LiveReload
+
+Hugo provides built-in LiveReload which watches for any changes to the source content and automatically reloads the site when changes are detected.
+
+1. Pull the currently used USWDS Hugo theme revision to your locally cloned copy of the OSCAL repo by executing the following command from within the folder of the git repo
+
+ ```
+git submodule update --init
+```
+
+2. Verify that Hugo is installed
+
+```
+hugo version
+```
+NOTE: The extended version of Hugo is required. The reported version should include the word "extended".
+
+3. Navigate into the `docs/` directory
+
+```
+cd docs
+```
+
+4. Start the Hugo server
+
+```
+hugo server -v --debug --minify
+```
+
+alternatively, you may bind Hugo to a network adapter on your workstation using its assigned IP address
+
+```
+hugo server -v --debug --minify --bind [ipv4-address] -b http://[ipv4-address]:1313/fedramp-automation
+```
+
+5. Open your browser and navigate to `http://localhost:1313/fedramp-automation` to view the locally built site.
+
+If you bound Hugo to an IP address, navigate to `http://[ipv4-address]:1313/fedramp-automation` either locally or with another device on the network.
+
+Whenever you make any changes to the content with the Hugo server running, you'll notice that the site automatically updates itself to reflect those changes.
+
+
+## Developing with Docker
+
+Coming soon:  The site will be available as a Docker container.  
+
+<!--
+The website can also be developed and built using the included Docker resources.
+
+Assuming you've [installed Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/) for your system, you can build and serve the site using Docker Compose as follows:
+
+```
+docker-compose build
+docker-compose up
+```
+
+Once the site is running, it can be accessed at http://localhost:1313/fedramp-automation. 
+-->

docs/archetypes/default.md

@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
+

docs/config.yaml

@@ -0,0 +1,66 @@
+title: "FedRAMP Automation"
+baseURL: https://automation.fedramp.gov
+relativeURLs: true
+canonifyURLs: true
+defaultContentLanguage: en
+disableAliases: false
+languages:
+  en:
+    lang: en
+    languageName: English
+    weight: 1
+MetaDataFormat: "yaml"
+theme: "uswds"
+# googleAnalytics: UA-42404149-54
+enableGitInfo: true
+pygmentsCodeFences: true
+pygmentsCodefencesGuessSyntax: true
+pygmentsUseClasses: true
+markup:
+  goldmark:
+    extensions:
+      typographer: false
+    parser:
+      autoHeadingID: true
+#      autoHeadingIDType: blackfriday
+    renderer:
+      unsafe: true
+  highlight:
+    guessSyntax: true
+params:
+  header:
+    project_shortname: "FedRAMP Automation"
+    project_name: "FedRAMP Automation"
+  page_repo_path: https://github.com/GSA/fedramp-automation/tree/feature-guides-updates/docs
+  # ** Change this on release ***
+  contentRepoPath: https://github.com/usnistgov/oscal-content/tree/master
+  searchAffiliate: oscal
+  sidenav:
+#    debug: true
+# menu:
+#   secondary:
+#   - name: Github
+#     url: https://github.com/GSA/fedramp-automation
+#     weight: 90
+module:
+  mounts:
+#  - source: content
+#    target: content
+  - source: static
+    target: static
+#  - source: ../xml
+#    target: static/artifacts/xml
+#  - source: ../json
+#    target: static/artifacts/json
+#  - source: ../content
+#    target: static/artifacts/content
+#  - source: layouts
+#    target: layouts
+#  - source: data
+#    target: data
+#  - source: assets
+#    target: assets
+#  - source: i18n
+#    target: i18n
+#  - source: archetypes
+#    target: archetypes

docs/content/_index.md

@@ -0,0 +1,19 @@
+---
+title: "FedRAMP Automation"
+---
+{{% usa-hero image="img/homepage-banner-desktop.jpg" calloutText="Automating" calloutAltText="Control-Based Assessments" buttonURL="/about/" buttonText="Learn More" %}}
+Using OSCAL to streamline and<br>
+automate risk management processes
+{{% /usa-hero %}}
+
+{{% usa-tagline caption="Modernizing Security Assessments, System Authorizations, and Continuous Monitoring" %}}
+OSCAL offers a number of benefits to streamlining and automating components of the authorization process. Below are just a few examples:
+
+- **Cloud Service Providers (CSPs)** are able to create their System Security Plans (SSPs) more rapidly and accurately, validating much of their content before submission to the government for review.
+- **Third Party Assessment Organizations (3PAOs)** are able to automate the planning, execution, and reporting of cloud assessment activities.
+- **Agencies** are able to expedite their reviews of the FedRAMP security authorization packages.
+The FedRAMP Program Management Office (PMO) expects to be able to build tooling to further reduce the cost and improve the quality of security reviews.
+
+[Get started](/start) with FedRAMP OSCAL today.
+{{% /usa-tagline %}}
+

docs/content/about/_index.md

@@ -0,0 +1,17 @@
+---
+title: More about FedRAMP OSCAL
+heading: Learn more about FedRAMP OSCAL
+menu:
+  primary:
+    name: About
+    weight: 1
+toc:
+  enabled: true
+---
+
+Coming Soon: Overview of FedRAMP OSCAL...
+
+# Why OSCAL at FedRAMP?
+
+Coming Soon: Description of FedRAMP's OSCAL adoption program
+

docs/content/about/faq.md

@@ -0,0 +1,14 @@
+---
+title: FAQs
+heading: Frequently Asked Questions
+menu:
+  primary:
+    name: FAQs
+    parent: About
+    weight: 9
+toc:
+  enabled: true
+---
+
+Coming Soon: List of FAQs and answers
+

docs/content/about/release.md

@@ -0,0 +1,14 @@
+---
+title: Release Strategy
+heading: Release Strategy
+menu:
+  primary:
+    name: Release Strategy
+    parent: About
+    weight: 2
+toc:
+  enabled: true
+---
+
+Coming Soon: Description of FedRAMP's OSCAL release strategy
+

docs/content/contact/_index.md

@@ -0,0 +1,14 @@
+---
+title: Contact Us
+description: Contact Us
+menu:
+  primary:
+    name: Contact Us
+    weight: 500
+toc:
+  enabled: true
+---
+
+We want to hear from you. All development efforts have been performed openly and we are seeking your feedback on our progress to date. Will these machine-readable formats and guidance aid your organization in going through the authorization process efficiently? Do you have any further ideas to enhance the work? Let us know!
+
+If you have questions or feedback, please provide comments either via email to [[email protected]](mailto:[email protected]) or as a comment to an existing issue  within the [FedRAMP Automation repository](https://github.com/GSA/fedramp-automation/issues).

docs/content/guides/_index.md

@@ -0,0 +1,52 @@
+---
+title: FedRAMP OSCAL Guides
+heading: FedRAMP OSCAL Guides
+menu:
+  primary:
+    name: Documentation
+    weight: 100
+suppresstopiclist: false
+sidenav:
+  #focusrenderdepth: 1
+  inactiverenderdepth: 1
+  activerenderdepth: 2
+toc:
+  enabled: true
+---
+
+## 1.1. Who Should Use These Guides?
+These Guides are intended for technical staff and tool developers implementing solutions for importing, exporting, and manipulating Open Security Controls Assessment Language (OSCAL)-based FedRAMP System Security Plan (SSP) content.
+
+It provides guidance and examples intended to guide an organization in the production and use of OSCAL-based FedRAMP-compliant SSP files. Our goal is to enable your organization to develop tools that will seamlessly ensure these standards are met so your security practitioners can focus on SSP content and accuracy rather than formatting and presentation.
+
+Refer to the *Guide to OSCAL-based FedRAMP Content* for foundational information and core concepts.
+
+<!-- <img style="float: right;" src="/img/refer-to.png"> -->
+
+{{<callout>}}
+  <span style="color: red">Refer to the [Guide to OSCAL-based Content](/guides/general/) for foundational information and core concepts</span>
+{{</callout>}}
+
+## 1.2. Related Documents
+This document does not stand alone. It provides information specific to developing tools to create and manage OSCAL-based, FedRAMP-compliant SSPs. 
+
+The [*Guide to OSCAL-based FedRAMP Content*](/guides/general/), contains foundational information and core concepts, which apply to all OSCAL-based FedRAMP guides. This document contains several references to that content guide.
+
+## 1.3. Basic Terminology
+XML and JSON use different terminology. Instead of repeatedly clarifying format-specific terminology, this document uses the following format-agnostic terminology through the document. 
+
+|**TERM**|**XML EQUIVALENT**|**JSON EQUIVALENT**|
+| :- | :- | :- |
+|**Field**|A single element or node that can hold a value or an attribute|A single object that can hold a value or property|
+|**Flag**|Attribute|Property|
+|**Assembly**|A collection of elements or nodes. Typically, a parent node with one or more child nodes.|A collection of objects. Typically, a parent object with one or more child objects.|
+
+These terms are used by National Institute of Standards and Technology (NIST) in the creation of OSCAL syntax.
+
+Throughout this document, the following words are used to differentiate between requirements, recommendations, and options.
+
+|**TERM**|**MEANING**|
+| :- | :- |
+|**must**|Indicates a required action.|
+|**should**|Indicates a recommended action, but not necessarily required.|
+|**may**|Indicates an optional action.|