Merge pull request #98 from anweiss/slate

Merging slate doc framework and initial docset migration

.dockerignore

@@ -0,0 +1,7 @@
+Vagrantfile
+build/
+.gitignore
+.git/
+.travis.yml
+deploy.sh
+.github/

.gitignore

@@ -0,0 +1,27 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.DS_STORE
+build/
+.cache
+.vagrant
+.sass-cache
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+.idea/
+
+# VSCode
+.vscode/

.travis.yml

@@ -0,0 +1,10 @@
+sudo: false
+
+language: ruby
+
+rvm:
+  - 2.3.3
+  - 2.4.0
+
+cache: bundler
+script: bundle exec middleman build

Dockerfile

@@ -0,0 +1,9 @@
+FROM ruby:2.3-alpine
+RUN apk add --update nodejs g++ make
+COPY Gemfile Gemfile.lock /usr/src/app/
+WORKDIR /usr/src/app
+RUN bundle install
+COPY . /usr/src/app
+VOLUME /usr/src/app
+EXPOSE 4567
+CMD ["bundle", "exec", "middleman", "server", "--watcher-force-polling"]

Gemfile

@@ -0,0 +1,12 @@
+ruby '>=2.3.1'
+source 'https://rubygems.org'
+
+# Middleman
+gem 'middleman', '~>4.2.1'
+gem 'middleman-syntax', '~> 3.0.0'
+gem 'middleman-autoprefixer', '~> 2.7.0'
+gem "middleman-sprockets", "~> 4.1.0"
+gem 'middleman-livereload'
+gem 'rouge', '~> 2.0.5'
+gem 'redcarpet', '~> 3.4.0'
+gem 'nokogiri', '~> 1.6.8'

Gemfile.lock

@@ -0,0 +1,141 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.0.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    addressable (2.5.0)
+      public_suffix (~> 2.0, >= 2.0.2)
+    autoprefixer-rails (6.6.1)
+      execjs
+    backports (3.6.8)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.12.2)
+    compass-import-once (1.0.5)
+      sass (>= 3.2, < 3.5)
+    concurrent-ruby (1.0.4)
+    contracts (0.13.0)
+    dotenv (2.2.0)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    erubis (2.7.0)
+    eventmachine (1.2.5)
+    execjs (2.7.0)
+    fast_blank (1.0.0)
+    fastimage (2.0.1)
+      addressable (~> 2)
+    ffi (1.9.17)
+    haml (4.0.7)
+      tilt
+    hamster (3.0.0)
+      concurrent-ruby (~> 1.0)
+    hashie (3.5.1)
+    http_parser.rb (0.6.0)
+    i18n (0.7.0)
+    kramdown (1.13.2)
+    listen (3.0.8)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    memoist (0.15.0)
+    middleman (4.2.1)
+      coffee-script (~> 2.2)
+      compass-import-once (= 1.0.5)
+      haml (>= 4.0.5)
+      kramdown (~> 1.2)
+      middleman-cli (= 4.2.1)
+      middleman-core (= 4.2.1)
+      sass (>= 3.4.0, < 4.0)
+    middleman-autoprefixer (2.7.1)
+      autoprefixer-rails (>= 6.5.2, < 7.0.0)
+      middleman-core (>= 3.3.3)
+    middleman-cli (4.2.1)
+      thor (>= 0.17.0, < 2.0)
+    middleman-core (4.2.1)
+      activesupport (>= 4.2, < 5.1)
+      addressable (~> 2.3)
+      backports (~> 3.6)
+      bundler (~> 1.1)
+      contracts (~> 0.13.0)
+      dotenv
+      erubis
+      execjs (~> 2.0)
+      fast_blank
+      fastimage (~> 2.0)
+      hamster (~> 3.0)
+      hashie (~> 3.4)
+      i18n (~> 0.7.0)
+      listen (~> 3.0.0)
+      memoist (~> 0.14)
+      padrino-helpers (~> 0.13.0)
+      parallel
+      rack (>= 1.4.5, < 3)
+      sass (>= 3.4)
+      servolux
+      tilt (~> 2.0)
+      uglifier (~> 3.0)
+    middleman-livereload (3.4.6)
+      em-websocket (~> 0.5.1)
+      middleman-core (>= 3.3)
+      rack-livereload (~> 0.3.15)
+    middleman-sprockets (4.1.0)
+      middleman-core (~> 4.0)
+      sprockets (>= 3.0)
+    middleman-syntax (3.0.0)
+      middleman-core (>= 3.2)
+      rouge (~> 2.0)
+    mini_portile2 (2.1.0)
+    minitest (5.10.1)
+    nokogiri (1.6.8.1)
+      mini_portile2 (~> 2.1.0)
+    padrino-helpers (0.13.3.3)
+      i18n (~> 0.6, >= 0.6.7)
+      padrino-support (= 0.13.3.3)
+      tilt (>= 1.4.1, < 3)
+    padrino-support (0.13.3.3)
+      activesupport (>= 3.1)
+    parallel (1.10.0)
+    public_suffix (2.0.5)
+    rack (2.0.1)
+    rack-livereload (0.3.16)
+      rack
+    rb-fsevent (0.9.8)
+    rb-inotify (0.9.8)
+      ffi (>= 0.5.0)
+    redcarpet (3.4.0)
+    rouge (2.0.7)
+    sass (3.4.23)
+    servolux (0.12.0)
+    sprockets (3.7.1)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    thor (0.19.4)
+    thread_safe (0.3.5)
+    tilt (2.0.6)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    uglifier (3.0.4)
+      execjs (>= 0.3.0, < 3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  middleman (~> 4.2.1)
+  middleman-autoprefixer (~> 2.7.0)
+  middleman-livereload
+  middleman-sprockets (~> 4.1.0)
+  middleman-syntax (~> 3.0.0)
+  nokogiri (~> 1.6.8)
+  redcarpet (~> 3.4.0)
+  rouge (~> 2.0.5)
+
+RUBY VERSION
+   ruby 2.3.3p222
+
+BUNDLED WITH
+   1.16.0

LICENSE

@@ -0,0 +1,13 @@
+Copyright 2008-2013 Concur Technologies, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.

README.md

@@ -1,15 +1,60 @@
-# Open Security Controls Assessment Language (OSCAL) 
+# OSCAL Documentation
 
-NIST is currently developing the Open Security Controls Assessment Language (OSCAL). OSCAL is a standard for representing information pertaining to the publication, implementation, and assessment of security controls in XML-based formats. A *control* is a safeguard or countermeasure designed to satisfy a set of defined security and/or privacy requirements. A set of security control definitions from a single source is known as an OSCAL *catalog*. Another important OSCAL concept is a *profile*, which is a set of security requirements for which meeting each requirement necessitates implementing one or more security controls. A profile is also called a *baseline* or *overlay*.
+## Documentation Development
 
-OSCAL is attempting to address a number of challenges around security controls and security control assessment. The core challenge, and one of the primary reasons for creating OSCAL, is that concepts like security controls and profiles are represented today largely in proprietary ways. In many cases they are written in prose documents that are imprecise, lead to differences in interpretation, and are not machine-readable, meaning that the prose instructions require someone to do data entry into a tool in order for the tool to use the information. 
+The OSCAL documentation is developed using the [Slate](https://github.com/lord/slate) platform. Below are instructions for standing up your local development environment.
 
-Organizations are also struggling with information systems that have many different components. Some components require the use of different profiles per component; this is commonly the case with cloud environments. Also, cloud environments can be multitenant or have mixed ownership of components. We need to be able to assess the security of these systems against a number of requirements, owners, etc.—to do that simultaneously and provide these views to stakeholders. 
+The [`source/`](source/) directory contains the editable markdown files. If you prefer, you can edit the markdown files directly without having to install any of the devlopment tooling described below.
 
-On top of that there are situations where a single system needs to support multiple regulatory frameworks. For example, the U.S. Department of Veterans Affairs is a federal agency (Federal Information Security Modernization Act (FISMA) and NIST Cybersecurity Framework requirements) and a healthcare institution (Health Insurance Portability and Accountability Act (HIPAA) requirements) that has credit card transactions (Payment Card Industry Data Security Standard (PCI DSS)). There is no shortage of requirements for some organizations that have multiple regulatory frameworks. 
+## Developing with Docker
 
-Assessing all these security controls is extremely complex. Because of that complexity, it’s largely a manual process today. The OSCAL project is trying to change that by standardizing how security controls are represented, how a control implementation for a given system is represented, and how that information is best used and reports generated in a standardized way that can be used by both humans and machines. That means formats are needed that can be generated by machines for communicating with other machines, but can also easily be reformatted so humans can read the information. By standardizing the representation of this information, OSCAL information can be interoperable by having a well-defined specification with information that’s going to be used, imported, and used interoperably for security control assessments. The goal is to keep OSCAL as simple as possible and provide extensive automation for tools to use.
+You can quickly and easily get started with doc development using Docker. You can get Docker for your appropriate platform [here](https://www.docker.com/community-edition). Once you've installed Docker, you can use the included `Dockerfile` and `docker-compose.yml` files to spin up a documentation server that supports live reload.
 
-OSCAL may be useful for many people, including operations personnel, security and privacy personnel, auditors and assessors, and policy personnel.
+    $ docker-compose up
 
-TBD: Add pointers to additional information. May want one for an OSCAL presentation.
+You can then launch your web browser and connect to `http://localhost:4567` to view the documentation. As you make updates to the source, the browser will automatically refresh to reflect the changes.
+
+## Developing without Docker
+
+If you prefer not to use Docker for local development, you can also install the required components directly onto your machine. You'll need the following:
+
+- Ruby 2.3.1
+  - On macOS, it's best to install using [Homebrew](https://www.ruby-lang.org/en/documentation/installation/#homebrew)
+  - On Linux, you can install via your distro's [package manager](https://www.ruby-lang.org/en/documentation/installation/#package-management-systems)
+  - On Windows, use [RubyInstaller](https://rubyinstaller.org/) or Windows Subsystem for Linux (WSL)
+- [Bundler](http://bundler.io/) - `gem install bundler`
+
+Install the dependencies:
+
+    $ bundle install
+
+You can then initialize and start the development server as follows:
+
+    $ bundle exec middleman server --watcher-force-polling
+
+Launch your web browser and connect to `http://localhost:4567` to view the docs. As you make changes to the source, the web page will automatically refresh.
+
+## Publishing to pages.nist.gov
+
+In order to publish to pages.nist.gov, the static documents needs to be built. The commands below will generate static documentation in the [`build/`](build/) directory.
+
+Using Docker:
+
+    $ docker build -t oscal-docs .
+    $ docker run --rm -v $PWD:/usr/src/app/source -w /usr/src/app/source oscal-docs bundle exec middleman build --clean
+
+Without Docker:
+
+    $ bundle exec middleman build --clean
+
+## Updating Slate
+
+You'll need to take into account any customizations you've made to the core framework before updating. Nonetheless, if it is deemed that the Slate framework itself needs to be updated, you'll first need to fork the upstream [`lord/slate`](https://github.com/lord/slate) repository. You can then set an upstream remote (if you haven't already) to your fork and fetch the latest changes as follows:
+
+    $ git remote add slate-upstream <your-slate-fork.git>
+    $ git fetch slate-upstream
+
+Then, checkout the `docs` branch and create a merge commit from the `slate-upstream/master` branch, correcting any merge conflicts as necessary. Bear in mind that if you've made a substantial number of framework/theming customizations, you may have a lot of merge conflicts to resolve.
+
+    $ git checkout docs
+    $ git merge slate-upstream/master

config.rb

@@ -0,0 +1,59 @@
+# Unique header generation
+require './lib/unique_head.rb'
+
+# Markdown
+set :markdown_engine, :redcarpet
+set :markdown,
+    fenced_code_blocks: true,
+    smartypants: true,
+    disable_indented_code_blocks: true,
+    prettify: true,
+    tables: true,
+    with_toc_data: true,
+    no_intra_emphasis: true,
+    renderer: UniqueHeadCounter
+
+# Assets
+set :css_dir, 'stylesheets'
+set :js_dir, 'javascripts'
+set :images_dir, 'images'
+set :fonts_dir, 'fonts'
+
+# Activate the syntax highlighter
+activate :syntax
+ready do
+  require './lib/multilang.rb'
+end
+
+activate :sprockets
+
+activate :livereload, js_host: '0.0.0.0'
+
+activate :autoprefixer do |config|
+  config.browsers = ['last 2 version', 'Firefox ESR']
+  config.cascade  = false
+  config.inline   = true
+end
+
+# Github pages require relative links
+activate :relative_assets
+set :relative_links, true
+
+# Build Configuration
+configure :build do
+  # If you're having trouble with Middleman hanging, commenting
+  # out the following two lines has been known to help
+  activate :minify_css
+  activate :minify_javascript
+  # activate :relative_assets
+  # activate :asset_hash
+  # activate :gzip
+end
+
+# Deploy Configuration
+# If you want Middleman to listen on a different port, you can set that below
+set :port, 4567
+
+helpers do
+  require './lib/toc_data.rb'
+end