Skip to content

Commit 42d2ea4

Browse files
steve-lyonssteve-lyons
authored
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.
1 parent 0813f0f commit 42d2ea4

26 files changed

+1036
-26
lines changed

‎404.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
# example 404.md
3+
4+
layout: default
5+
permalink: /404.html
6+
---
7+
8+
# Page Not Found
9+
10+
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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Critical items to know are:
1414
- changed behaviour
1515

1616
## [master](https://github.com/vsoch/docsy-jekyll/tree/master)
17+
- adding support for documentation versioning (0.0.25)
1718
- adding more verbose example for subfolders (0.0.24)
1819
- sidebar fix to support multiple top level menus (0.0.23)
1920
- added support for github_branch (default 'master') in config (0.0.22)

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
0.0.24
1+
0.0.25

‎_config.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,24 @@ twitter: vsoch
3939
linkedin: vsochat
4040
dockerhub: vanessa
4141

42+
# These options are used to configure the locations of your version history when you want to serve versioned documents
43+
version_params:
44+
version_menu: "Release"
45+
version_dir: Archive
46+
tocversion_dir: versions
47+
versioning: true
48+
49+
# Disable so older versions cannot be searched
50+
allow_search: true
51+
52+
# Allow these versions to be searched
53+
search_versions:
54+
- Previous
55+
latest: Current
56+
versions:
57+
- Current
58+
- Previous
59+
4260
# Should there be feedback buttons at the bottom of pages?
4361
feedback: true
4462

‎_data/toc-mapping.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# This file can be used to explicitly map a release to a specific table-of-contents
2+
# (TOC). You'll want to use this after any revamps to information architecture, to ensure
3+
# that the navigation for older versions still work.
4+
5+
Current: toc
6+
Previous: previous-toc

‎_data/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
url: "docs/getting-started#development"
1111
- title: Customization
1212
url: "docs/getting-started#customization"
13+
- title: Versioning
14+
url: "docs/versioning"
1315
- title: "About"
1416
url: "about"
1517
- title: "News"

‎_data/versions/previous-toc.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
- title: Documentation
2+
url: docs
3+
links:
4+
- title: "Getting Started"
5+
url: "docs/getting-started"
6+
children:
7+
- title: Features
8+
url: "docs/getting-started#getting-started"
9+
- title: Development
10+
url: "docs/getting-started#development"
11+
- title: Customization
12+
url: "docs/getting-started#customization"
13+
- title: "About"
14+
url: "about"
15+
- title: "News"
16+
url: "news"
17+
- title: "Extras"
18+
url: "docs/extras"
19+
links:
20+
- title: Quizzes
21+
url: "docs/extras/example-quiz"
22+
- title: Tags Page
23+
url: "tags"

‎_docs/Archive/Previous/example-page.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: A Nested Page
3+
description: An example of a nested page
4+
---
5+
6+
# A Nested Page
7+
8+
This is an example of a page that doesn't have a permalink defined, and
9+
is not included in the table of contents (`_data/toc.yml`). This means
10+
that it will render based on it's path. Since it's in `docs/example-page.md`,
11+
the url will be `docs/example-page/`.
12+
13+
## Link to a subfolder
14+
15+
Now let's say we want to link to a subfolder, specifically with this
16+
setup:
17+
18+
```
19+
docs/
20+
example-page.md (-- we are here
21+
subfolder/
22+
example-page.md (-- we want to link here
23+
```
24+
25+
You can provide the relative path to the file, like `subfolder/example-page.md`
26+
and Jekyll will handle parsing it. For example:
27+
28+
- [here is that link](subfolder/example-page)
29+
30+
And {% include doc.html name="here" path="subfolder/example-page" %} is the same link,
31+
but generated with the include statement:
32+
33+
```
34+
{% raw %}{% include doc.html name="here" path="subfolder/example-page" %}{% endraw %}
35+
```
36+

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: Quiz
3+
description: How to add interactive quizzes to your site.
4+
---
5+
6+
# Quizzes
7+
8+
As of version 0.0.12, docsy-jekyll has support for basic quizzes! These are
9+
intended to help educate your users about the content of your documentation.
10+
For a quiz, you can add a new file to the folder `_data/quizzes`, and write a
11+
questions file based on the format shown in `_data/quizzes/example-quiz.yml`.
12+
Here is a simple example of a multiple choice question (which can also serve as
13+
True/False):
14+
15+
```yaml
16+
title: This is the Quiz Title
17+
randomized: false
18+
questions:
19+
20+
- type: "multiple-choice"
21+
question: "True or False, Pittsburgh is West of Philadelphia"
22+
items:
23+
- choice: True
24+
correct: true
25+
- choice: False
26+
correct: false
27+
followup: |
28+
The answer is True! Pittsburgh is 304.9 miles West of
29+
Philadelphia, or approximately a car ride of
30+
4 hours and 52 minutes. Buckle up!
31+
```
32+
33+
The quiz is rendered with a "Show Answer" button below each question, and when
34+
the user clicks it, any questions that are flagged with `correct: true` will be
35+
bolded, and if a followup section is included, it will be displayed.
36+
See the live example at the end of this page.
37+
38+
## Options
39+
40+
#### Title
41+
42+
If you include a title, it will be rendered at the top of the quiz. This is
43+
optional - you can leave it out and add it before the include on the page.
44+
45+
#### Random
46+
47+
If you want your questions to be presented randomly, just add randomized: true
48+
to the data.
49+
50+
51+
## Example Quiz
52+
53+
If I want to include the quiz located at `_data/quizzes/example-quiz.yml`, I
54+
can do so like this:
55+
56+
```
57+
{% raw %}{% include quiz.html file='example-quiz' %}{% endraw %}
58+
```
59+
60+
The rendered quiz is shown here:
61+
62+
63+
{% include quiz.html file='example-quiz' %}

‎_docs/Archive/Previous/extras/index.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Extras
3+
description: Extras, including quizzes.
4+
tags:
5+
- survey
6+
---
7+
8+
# Extras
9+
10+
Extras include other integrations that aren't relevant to style or customization,
11+
but can further enhance your documentation pages. Currently, we have support
12+
for adding interactive quizzes.
13+
14+
- [Quizzes](example-quiz)
15+
- [Tags]({{ site.baseurl }}/tags/)
16+
17+
Would you like to see another question type, or another kind of extra? Please [open an issue]({{ site.repo }}/issues/new).

0 commit comments

Comments
 (0)