Add versioning options (#69)

* Add versioning options
Add optional versioning to the docs content
* Archived docs now live in their own subdirectory
Archive docs now live in their own archive subdirectory of _docs
* Fix syntax typo
Fix syntax typo in default.html
* Apply suggestions from code review
* Use subdirectory for toc files
Use subdirectory for toc files and update the documentation on how to set it up.
* Additional info in the versioning Docs
Additional info in the versioning Docs to provide commands etc
* Update _config.yml to have default tocversion_dir
Update _config.yml to have a default tocversion_dir and a description to the settings too.
* adding support for search filtered versioning
the user can enable which versions to include in search, and they will have a badge that shows it,
with the current using site.tag_color and others in secondary (gray) color.
* tweak spacing in search.js
* Add Search and Versioning section to docs
Add Search and Versioning section to docs to show what is displayed if enabled.

404.md

@@ -0,0 +1,10 @@
+---
+# example 404.md
+
+layout: default
+permalink: /404.html
+---
+
+# Page Not Found
+
+Unfortunately we were unable to find the page you requested. It could be the page doesn't exist or only exists for a specific version of these documents so please use the search feature to see if you are able to locate the information you were after.

CHANGELOG.md

@@ -14,6 +14,7 @@ Critical items to know are:
  - changed behaviour
 
 ## [master](https://github.com/vsoch/docsy-jekyll/tree/master)
+ - adding support for documentation versioning (0.0.25)
  - adding more verbose example for subfolders (0.0.24)
  - sidebar fix to support multiple top level menus (0.0.23)
  - added support for github_branch (default 'master') in config (0.0.22)

VERSION

@@ -1 +1 @@
-0.0.24
+0.0.25

_config.yml

@@ -39,6 +39,24 @@ twitter: vsoch
 linkedin: vsochat
 dockerhub: vanessa
 
+# These options are used to configure the locations of your version history when you want to serve versioned documents
+version_params:
+  version_menu: "Release"
+  version_dir: Archive
+  tocversion_dir: versions
+  versioning: true
+
+  # Disable so older versions cannot be searched
+  allow_search: true  
+
+  # Allow these versions to be searched
+  search_versions:
+    - Previous
+  latest: Current
+  versions:
+    - Current
+    - Previous
+
 # Should there be feedback buttons at the bottom of pages?
 feedback: true
 

_data/toc-mapping.yml

@@ -0,0 +1,6 @@
+# This file can be used to explicitly map a release to a specific table-of-contents
+# (TOC). You'll want to use this after any revamps to information architecture, to ensure
+# that the navigation for older versions still work.
+
+Current: toc
+Previous: previous-toc

_data/toc.yml

@@ -10,6 +10,8 @@
           url: "docs/getting-started#development"
         - title: Customization
           url: "docs/getting-started#customization"
+    - title: Versioning
+      url: "docs/versioning"
     - title: "About"
       url: "about"
     - title: "News"

_data/versions/previous-toc.yml

@@ -0,0 +1,23 @@
+- title: Documentation
+  url: docs
+  links:
+    - title: "Getting Started"
+      url: "docs/getting-started"
+      children:
+        - title: Features
+          url: "docs/getting-started#getting-started"
+        - title: Development
+          url: "docs/getting-started#development"
+        - title: Customization
+          url: "docs/getting-started#customization"
+    - title: "About"
+      url: "about"
+    - title: "News"
+      url: "news"
+- title: "Extras"
+  url: "docs/extras"
+  links:
+    - title: Quizzes
+      url: "docs/extras/example-quiz"
+    - title: Tags Page
+      url: "tags"

_docs/Archive/Previous/example-page.md

@@ -0,0 +1,36 @@
+---
+title: A Nested Page
+description: An example of a nested page
+---
+
+# A Nested Page
+
+This is an example of a page that doesn't have a permalink defined, and
+is not included in the table of contents (`_data/toc.yml`). This means
+that it will render based on it's path. Since it's in `docs/example-page.md`,
+the url will be `docs/example-page/`.
+
+## Link to a subfolder
+
+Now let's say we want to link to a subfolder, specifically with this
+setup:
+
+```
+docs/
+  example-page.md  (-- we are here
+  subfolder/
+     example-page.md  (-- we want to link here
+```
+
+You can provide the relative path to the file, like `subfolder/example-page.md`
+and Jekyll will handle parsing it. For example:
+
+ - [here is that link](subfolder/example-page)
+
+And {% include doc.html name="here" path="subfolder/example-page" %} is the same link, 
+but generated with the include statement:
+
+```
+{% raw %}{% include doc.html name="here" path="subfolder/example-page" %}{% endraw %}
+```
+

_docs/Archive/Previous/extras/example-quiz.md

@@ -0,0 +1,63 @@
+---
+title: Quiz
+description: How to add interactive quizzes to your site.
+---
+
+# Quizzes
+
+As of version 0.0.12, docsy-jekyll has support for basic quizzes! These are
+intended to help educate your users about the content of your documentation.
+For a quiz, you can add a new file to the folder `_data/quizzes`, and write a 
+questions file based on the format shown in `_data/quizzes/example-quiz.yml`.
+Here is a simple example of a multiple choice question (which can also serve as 
+True/False):
+
+```yaml
+title: This is the Quiz Title
+randomized: false
+questions:
+
+ - type: "multiple-choice"
+   question: "True or False, Pittsburgh is West of Philadelphia"
+   items:
+    - choice: True
+      correct: true
+    - choice: False
+      correct: false
+   followup: | 
+      The answer is True! Pittsburgh is 304.9 miles West of 
+      Philadelphia, or approximately a car ride of 
+      4 hours and 52 minutes. Buckle up!
+```
+
+The quiz is rendered with a "Show Answer" button below each question, and when
+the user clicks it, any questions that are flagged with `correct: true` will be 
+bolded, and if a followup section is included, it will be displayed.
+See the live example at the end of this page.
+
+## Options
+
+#### Title
+
+If you include a title, it will be rendered at the top of the quiz. This is
+optional - you can leave it out and add it before the include on the page.
+
+#### Random
+
+If you want your questions to be presented randomly, just add randomized: true
+to the data.
+
+
+## Example Quiz
+
+If I want to include the quiz located at `_data/quizzes/example-quiz.yml`, I 
+can do so like this:
+
+```
+{% raw %}{% include quiz.html file='example-quiz' %}{% endraw %}
+```
+
+The rendered quiz is shown here:
+
+
+{% include quiz.html file='example-quiz' %}

_docs/Archive/Previous/extras/index.md

@@ -0,0 +1,17 @@
+---
+title: Extras
+description: Extras, including quizzes.
+tags:
+ - survey
+---
+
+# Extras
+
+Extras include other integrations that aren't relevant to style or customization,
+but can further enhance your documentation pages. Currently, we have support
+for adding interactive quizzes.
+
+ - [Quizzes](example-quiz)
+ - [Tags]({{ site.baseurl }}/tags/)
+
+Would you like to see another question type, or another kind of extra? Please [open an issue]({{ site.repo }}/issues/new).