diff --git a/_docs/example-page.md b/_docs/example-page.md deleted file mode 100644 index 641ae72..0000000 --- a/_docs/example-page.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -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 %} -``` - diff --git a/_docs/extras/example-quiz.md b/_docs/extras/example-quiz.md deleted file mode 100644 index 59dfebe..0000000 --- a/_docs/extras/example-quiz.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -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' %} diff --git a/_docs/extras/index.md b/_docs/extras/index.md deleted file mode 100644 index 0f6f13f..0000000 --- a/_docs/extras/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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). diff --git a/_docs/getting-started.md b/_docs/getting-started.md deleted file mode 100644 index d028b9b..0000000 --- a/_docs/getting-started.md +++ /dev/null @@ -1,390 +0,0 @@ ---- -title: Getting Started -tags: - - jekyll - - github -description: Getting started with Docsy Jekyll ---- - -# Getting Started - -## Features - -### User Interaction - - -On the right side of any page, you'll notice links to edit the page, or -open an issue. This ensures that any time you have a question or want to -suggest or request a change, you can do so immediately and link directly -to the section of interest. The sections on the page also have permalinks so -you can link directly to them. - -### Search - -The entire site, including posts and documentation, is indexed and then available -for search at the top or side of the page. Give it a try! The content is rendered -into window data that is used by lunr.js to generate the search results. -If you want to exclude any file from search, add this to its front end matter: - -``` ---- -layout: null -excluded_in_search: true ---- -``` - -The example above is for a javascript file in the assets folder that is used as a template, -but should not be included in search. - -### External Search - -If you have an external site with a search GET endpoint (meaning one that ends -in `?q=`, then you can automatically link page tags to search this endpoint. -For example, on an HPC site I'd want a tag like "mpi" to do a search on -[http://ask.cyberinfrastructure.org](http://ask.cyberinfrastructure.org) for mpi. -See the [tags](#tags) section below for how to configure this. - -### Documentation - -Documentation pages should be written in the `docs` folder of the repository, -and you are allowed to use whatever level of nesting (subfolders) that -works for you! It's a Jekyll [collection](https://jekyllrb.com/docs/collections/), which means that you -can add other content (images, scripts) and it will be included for linking to. -To create subfolders with files, you can simply create new markdon files. For example: - - - `_docs/subfolder/example-page.md` renders to `http://localhost:4000/docsy-jekyll/docs/subfolder/example-page/` - - `_docs/subfolder.md` renders to `http://localhost:4000/docsy-jekyll/docs/subfolder/` - -And the page you are reading now renders from `_docs/getting-started.md` - -#### Organization - -The url that will render is based on the path. For example, if we had the following structure: - -``` -docs/ - getting-started.md - clusters/ - sherlock/ - getting-started.md -``` - -The first page (akin to the one you are reading) would render at it's path, -`/docs/getting-started/`. - - -#### Linking - -From that page, we could provide the -direct path in markdown to any subfolder to link to it, such as the second -getting started page for sherlock: - -``` -{% raw %}[example](clusters/sherlock/getting-started.md){% endraw %} -``` - -[Here](example-page) is an example link to a relative path of a file (`example-page.md`) -in the same directory, and from that page you can test linking to a subfolder. -In the case of not having a subfolder, we could write the link out directly: - -``` -{% raw %}[example]({{ site.baseurl }}/docs/clusters/sherlock/getting-started.md){% endraw %} -``` - -or just put the relative path: - -``` -{% raw %}[Here](example-page){% endraw %} -``` - -or better, there is a shortand trick! We can use the provided "includes" -template to do the same based on the path to create a link: - -``` -{% raw %}{% include doc.html name="Sherlock Cluster" path="clusters/sherlock/getting-started" %}{% endraw %} -``` -The path should be relative to the docs folder. - -### Pages - -The `pages` folder uses the same page layout, but is not part of the docs collection. -The two are provided to create a distinction between website pages (e.g., about, -feed.xml) and documentation pages. - -### Navigation - -Whether you place your page under "pages" or "docs," for those pages that you want added to the navigation, -you should add them to `_data/toc.yml`. If you've defined a `permalink` in the -front end matter, you can use that (e.g., "About" below). If you haven't and -want to link to docs, the url is the path starting with the docs folder. -Here is an example (currently the active example): - -```yaml -- 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: "Extras" - url: "docs/extras" - children: - - title: Quizzes - url: "docs/extras/example-quiz" - - title: "About" - url: "about" - - title: "News" - url: "news -``` - -If you want to add an external url for a parent or child, do this: - -```yaml - - title: GitHub Repository - external_url: https://www.github.com/vsoch/mkdocs-jekyll -``` - -### News Posts - -It might be the case that your site or group has news items that would -warrant sharing with the community, and should be available as a feed. -For this reason, you can write traditional [posts](https://jekyllrb.com/docs/posts/) in the `_posts` -folder that will parse into the site [feed]({{ site.baseurl }}/feed.xml) -The bottom of the page links the user to a post archive, where posts are organized -according to the year. - -### Buttons - -Buttons come in a nice array of colors. Here is the code for a basic example, -and you'd want to vary the `.btn-` to get different classes. - -```html - -``` - - - - - - - - -### Badges - -For news post items, it's nice to be able to tag it with something that indicates -a status, such as "warning" or "alert." For this reason, you can add badges to -the front end matter of any post page, and they will render colored by a type, -with the tag of your choice. For example, here is an example header for -a post: - -```yaml ---- -title: "Two Thousand Nineteen" -date: 2019-06-28 18:52:21 -categories: jekyll update -badges: - - type: warning - tag: warning-badge - - type: danger - tag: danger-badge ---- -``` - -And here is the post preview with the rendered badges that it produces: - -warning-badge -danger-badge - -And the other badges that you can define include success, info, secondary, -and primary. - -success-badge -info-badge -secondary-badge -primary-badge - -### Alerts - -{% include alert.html type="info" title="What is an alert?" content="An alert is a box that can stand out to indicate important information. You can choose from levels success, warning, danger, info, and primary. This example is an info box, and the code for another might look like this:" %} - -``` -{%raw%}{% include alert.html type="info" title="Here is another!" %}{%endraw%} -``` - -Just for fun, here are all the types: - -{% include alert.html type="warning" content="This is a warning" %} -{% include alert.html type="danger" content="This alerts danger!" %} -{% include alert.html type="success" content="This alerts success" %} -{% include alert.html type="info" content="This is useful information." %} -{% include alert.html type="primary" content="This is a primary alert" %} -{% include alert.html type="secondary" content="This is a secondary alert" %} - -### Quotes - -You can include block quotes to emphasize text. - -> Here is an example. Isn't this much more prominent to the user? - -## Development - -Initially (on OS X), you will need to setup [Brew](http://brew.sh/) which is a package manager for OS X and [Git](https://git-scm.com/). To install Brew and Git, run the following commands: - -```bash -/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -brew install git -``` - -If you are on Debian/Ubuntu, then you can easily install git with `apt-get` - -```bash -apt-get update && apt-get install -y git -``` - -### Install Jekyll - -You can also install Jekyll with brew. - -```bash -$ brew install ruby -$ gem install jekyll -$ gem install bundler -$ bundle install -``` - -On Ubuntu I do a different method: - -```bash -git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build -echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc -exec $SHELL -rbenv install 2.3.1 -rbenv global 2.3.1 -gem install bundler -rbenv rehash -ruby -v - -# Rails -curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash - -sudo apt-get install -y nodejs -gem install rails -v 4.2.6 -rbenv rehash - -# Jekyll -gem install jekyll -gem install github-pages -gem install jekyll-sass-converter - -rbenv rehash -``` - -### Get the code - -You should first fork the repository to your GitHub organization or username, -and then clone it. - -```bash -$ git clone https://github.com//mkdocs-jekyll.git docs -$ cd docs -``` - -You can clone the repository right to where you want to host the docs: - -```bash -$ git clone https://github.com//mkdocs-jekyll.git docs -$ cd docs -``` - - -### Serve - -Depending on how you installed jekyll: - -```bash -jekyll serve -# or -bundle exec jekyll serve -``` - - -### Preview - -We provide a [CircleCI](https://circleci.com/) configuration recipe that you -can use to preview your site on CircleCI before merging into master. You -should follow the instructions to [set up a project](https://circleci.com/docs/enterprise/quick-start/), -and then in the project settings be sure to enable building forked build requests, -and to cancel redundant builds. The preview will be built on CircleCI, and saved -to static files for you to browse. The only change you will need is to edit -the static files location to be the name of your repository, which is at te -bottom of the `.circleci/config.yml` file: - -```yaml - - store_artifacts: - path: ~/repo/_site - destination: mkdocs-jekyll -``` - -In the above, the destination should coincide with your repository name. -Remember that for most links, CircleCI won't honor an `index.html` file in a subfolder -(e.g., `subfolder/index.html` will not be served as `subfolder/`, so for example, -you might need to turn this: - -``` -https:///0/mkdocs-jekyll/docs/getting-started/ -``` -into this: - -``` -https:///0/mkdocs-jekyll/docs/getting-started/index.html -``` - -## Customization - -#### config.yml - -To edit configuration values, customize the [_config.yml](_config.yml). -Most are documented there, and please [open an issue](https://www.github.com/{{ site.github_user }}/{{ site.github_user }}/issues) if you have questions. - -#### Adding pages - -To add pages, write them into the [pages](pages) folder. -You define urls based on the `permalink` attribute in your pages, -and then add them to the navigation by adding to the content of [_data/toc.yml](_data/toc.yml). - -#### Tags - -If you include tags on a page, by default they will link to the [tags page]({{ site.url }}{{ site.baseurl }}/tags) on the site. However, if you define a `tag_search_endpoint` url in your configuration file, by clicking -the tag, the user will be taken to this page to search for it. As an example, -we define the current search endpoint to be Ask Cyberinfrastructure, and -page tags link to a search on it: - -```yaml -tag_search_endpoint: https://ask.cyberinfrastructure.org/search?q= -tag_color: danger # danger, success, warning, primary, secondary, info -``` - -Note that you can also choose a color! The tags appear at the top of the page, -as they do on this page. The tags should be defined like this in the front end -matter: - -```yaml -tags: - - jekyll - - github -``` - -They are appended to the first h1 block, so generally your pages should have a header. -If you comment out this variable, then each of your tags will link to it's appropriate -spot on the tags page linked above. - -```yaml -#tag_search_endpoint: https://ask.cyberinfrastructure.org/search?q= -tag_color: primary # danger, success, warning, primary, info, secondary -``` - diff --git a/_docs/subfolder.md b/_docs/subfolder.md deleted file mode 100644 index f19122d..0000000 --- a/_docs/subfolder.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: The Subfolder Page -description: An example of a subfolder page. ---- - -# A Subfolder 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`). diff --git a/_docs/versioning.md b/_docs/versioning.md deleted file mode 100644 index cd9cf0b..0000000 --- a/_docs/versioning.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Versioning your Docs -description: How to turn on and use versioning ---- - -# Versioning - -Versioning documentation is a useful feature that can be achieved using Docsy Jekyll. It allows you to take snapshots of your documentation that may align with a specific version of a product or service, or you may wish to just keep a historical view of the changes that have been made to your documents over time. - -{% include alert.html type="info" title="Note: This only allows you to version documents inside the _docs folder, it does not allow you to version any files outside of that, such as Pages, Posts etc." %} - -The following information will take you through the detailed setup of versioning your documentation but in summary there will be four tasks that need to be completed to version your documents. - -1. Copy the current _docs content into a subfolder of _docs/Archive (e.g., within a folder named by the version) -2. Add a corresponding table of contents to _data/versions -3. Update the _data/toc-mapping.yml file to point the new table of contents -4. Test your site locally to ensure it works as expected! - -## Implementation - -The way in which versioning is achieved is by duplicating your whole document directory and placing it inside an 'archive' subdirectory with the name of that version. The following illustrates what the base document root looks like *without* another version for this Docsy Jekyll site. - -``` -document root -│ -└─── _data -└─── _docs - └─── extras - └─── subfolder - example-page.md - getting-started.md - subfolder.md - versioning.md -``` -To create a version of this documentation we first create a folder with the version name we want to use inside of the 'archive' folder and copy all the files and folders from our root _docs folder into that new folder. You could use the following commands to achieve this: - -```shell -# Our last release is version "Previous" (could also be 1.0.0 or semver), we are pinning the docs to this version` -mkdir -p _docs/Archive/Previous -# copy all content under _docs except Archive into this new folder.` -cp -r _docs/!(Archive) _docs/Archive/Previous -``` - -After we do this, we end up with a structure shown below - the older documentation is moved into the folder 'Previous'. This step effectively takes a snapshot of our documents at a point in time and the expectation is that we will no longer maintain these pages. If you look at the structure of this site you will see the 'Previous' folder, which now holds our previous documentation, does not contain the versioning.md markdown file as this is new in the current release. This means that if you look at this page on the current site and then choose "Previous" from the version dropdown, you will get a 404 error (not found). - -

-document root
-│      
-└─── _data
-└─── _docs
-        └─── extras
-        └─── subfolder
-        └─── Archive
-              └─── Previous
-                  └─── extras
-                  └─── subfolder
-                  example-page.md
-                  getting-started.md
-                  subfolder.md
-        example-page.md
-        getting-started.md
-        subfolder.md
-        versioning.md
-
- -You would now continue to add, update or remove markdown files from the main _docs directory in order to work on the current version of your documentation. - -Once the versioning has been correctly configured and you have created a snapshot, you can access those documents by adding the version to the url to access that archived version (e.g. /docs/Archive/Previous/getting-started). - -To enable the users to interact with these versioned documents through the UI there needs to be some updates to the _config.yml file to setup and enable it. The following is a snippet from the _config.yml file specific to the versioning options that are available. - -```yml -version_params: - version_menu: "Release" - version_dir: Archive - tocversion_dir: versions - versioning: true - latest: current - allow_search: true - search_versions: - - main - - current - - beta - versions: - - main - - current - - beta - - v3.1 - - v3.0.1 - - v3.0 - - v2.4.5 - - v2.4.4 -``` - -### Versioning Options - - -| Parameter | Description | Values | -| --------- | ----------- | ------ | -| versioning | This determines whether the versioning functionality is enabled | true \| false -| version_menu | In addition to the version dropdown you can specify some text to display alongside it
If you do not wish to use this then make this value an empty string | Release -| version_dir | This is the directory where all the alternative versions of the documentation will be contained beneath the _docs directory
i.e. setting this to the value of Archive (Note: **No** trailing slash) will mean all alternative versions will be found in _docs/Archive/ | Archive -| tocversion_dir | This is the directory inside your _data directory where Docsy Jekyll will find the alternative TOC files that are used for other versions of the documentation. You can configure this to be whatever name you like, just ensure your other TOCs can be found there! | versions -| latest | From the list of versions this determines the one which relates to your base docs directory.
Note the url for your docs will not contain a version identifier for this particular version| current \| v3.1 -| allow_search | A boolean to indicate if we should allow searching over versions. If False, only the current is displayed in results | true \| false -| search_version | A list of versions to include in the search. Current or latest will be tagged with the site.tag_color, the rest will be gray | current \| previous -| versions | A list of versions you wish to display in the version dropdown
Note that there are several special keywords that can be used: current, main, alpha, beta, rc and pre, see below for more details | current \| v1.0 \| v2.1.3 - -{% include alert.html type="warning" title="Note: The versions listed must have the same name as the folder name in which that version of the documentation resides otherwise jekyll it will not find it! The exception is the version 'current' which does not have a separate folder and is used to inform jekyll to utilize the base _docs folder." %} - -### Version Keywords -There are six special keywords that can be used in the versions config. -* main -* alpha -* beta -* rc -* pre -* *current* - -The value **main**, is used to display the latest development version of the documentation, a banner is used to denote that the code and documentation maybe unstable and that they are not guaranteed to be correct or up to date and could change at any time. - -The value of **alpha**, **beta**, **rc** and **pre** are used to denote that the documentation is a pre-production version and as such a banner is displayed announcing that the code/documentation maybe unstable and the content in the pages are still work in progress so may not be completely up to date or correct. - -If you wish to utilize this feature then you must create folders within your _docs/*Archive* directory with the names of those you wish to use and place your documentation inside it/them. - -The value of **current** is used to align with the latest version of your documentation in your base _docs folder so there **doesn't** need to be a specific folder created and named 'current' to serve them. The name 'current', for the value of 'latest' in the previous example, can be changed to whatever you wish to name the current release but be aware that the version set in the _config.yml file also needs to match it! See the example below where we have called the latest release v3.2 rather than 'current' and we also have a version exactly named v3.2 too, as mentioned this version will point to your base _docs directory. - -```yml -version_params: - version_menu: "Release" - version_dir: Archive - tocversion_dir: versions - versioning: true - latest: v3.2 - versions: - - main - - v3.2 - - beta - - v3.1 -``` - -### Configuring Version Alerts - -Depending on the version keywords you may use Docsy Jekyll tries to determine if the documentation is historical (e.g. out of date) or is a upcoming release of information and will show one of the following banners to alert users to the fact that they are not reviewing the current version of the documentation. - -|![Historical Versions]({{ site.baseurl }}/assets/img/versionalertoutdated.png)| -|:--:| -| *This banner is shown for historical versions of your documentation* | - -|![Beta Versions]({{ site.baseurl }}/assets/img/versionalertbeta.png)| -|:--:| -| *This banner is shown for pre-production versions of your documentation* | - -|![Development Versions]({{ site.baseurl }}/assets/img/versionalertmain.png)| -|:--:| -| *This banner is shown for development versions of your documentation* | - -These banners can be customised to have the wording or imagery you require by altering the HTML in the _includes/versionalert.html file. - -## Table of Contents Handling (TOC) - -As with the documents, your TOC contents also need to be updated so they correctly point to the document versions you are viewing. - -You will need to update the toc file as the structure of your documentation/toc changes over time but as we have taken a snapshot of our documentation so we need to do the same thing for our toc so it reflects the document structure at that point in time too. You will see that for this site we have the versions of Current and Previous and you will see that the Current version has all the information about versioning which didn't exist in the prior version. - -To enable the TOC to change based on the version, we have to create a new toc file and name it {version}-toc.yml and it must be placed in a subdirectory of _data whose name is specified by the tocversion_dir parameter in the _config.yml file (for this site it can be found in the _data/versions subdirectory). We have created previous-toc.yml in the _data/versions directory that has the TOC structure for the prior version where we did not have the versioning.md file present. - - -To create this version of the toc file file we can use the following commands -```shell -# Our last release is version "Previous" so we want to create a TOC for that inside our versions directory -mkdir -p _data/versions -# copy the existing TOC file to our version subdirectory and name it as {version}-toc.yml -cp _data/toc.yml _data/versions/previous-toc.yml -``` - - -{% include alert.html type="info" title="Note: The toc.yml file will always be our current table of contents pointing to the most recent version of the documentation in the base of our _docs folder. When adding additional items to your toc.yml file you do not need to worry about the version identifier as that is taken care of by Docsy Jekyll when viewing alternative versions, continue to have the urls pointing to the files in the base docs directory." %} - -Here is what our current toc.yml file in our _data directory looks like, the previous-toc.yml file will look identical apart from omitting the 'Versioning' title and link which was added for this release, and of course will live in the versions subdirectory of _data as well. - -```yml -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: Versioning - url: "docs/versioning" - - 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" -``` - -Now not every version of your documentation will have a change in structure and therefore require an update to toc.yml. To remove this overhead a mapping file is used to tell Docsy Jekyll which TOC it should use for a particular version, -the benefit of this is that if the structure of your site does not change then you do not need to create an additional toc.yml file. - -You will have a toc-mapping.yml file in your _data directory and the contents will contain the code below to map a particular version with a particular TOC file to use. You need to update this file for each version you create even if you do not need to create a new TOC file. - -```yml -# 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 works. - -Current: toc -Previous: previous-toc -``` -**You do not need to prefix the name of the new TOC filename with the folder (in our case versions) as Docsy Jekyll will retrieve that from the _config.yml file and add that to the path.** - -{% include alert.html type="info" title="Note: If a version cannot be found in this mapping file then the standard toc.yml in the _data directory will be used instead." %} - -Because we added the versioning.md markdown file to this site we needed a new toc so that this new content could be accessed from the TOC menu. If we had only made an update to the content of the files that already existed, then we could have pointed Previous to toc in the yml above to use the same toc.yml file. - -## Versioning and Search - -As you will have seen in the [Versioning Options](#versioning-options) you have the ability to configure Docsy Jekyll to perform it's searches over the entire site's documentation, or only certain versions which you can specify. If you choose not to enable it in _config.yml (allow_search = false) then the searches that get performed will only be over the most current version of the documentation in your base _docs folder. If you prefer to have this enabled then you will need to provide a list of search versions (search_version in _config.yml) that you wish to be displayed if a match is found. The following image shows what your users would be shown if you have this enabled. You can see that the search was for the term 'start' and we have several results returned but two both for the 'Getting Started' topic. The reason for this is due to a result being returned within the current version as well as a result being returned for the previous version as denoted by the badges of 'Current' and 'Previous' below the titles. - - -| *Searching with Versioning enabled*| -|:--:| -|![Search with Versions]({{ site.baseurl }}/assets/img/docsy-jekyll-version-search.png) - - -## Issues with Permalinks - -Please do not use permalinks in your archive documentation Front Matter if you wish to use versioning as this will break the versioning system. If you have permalinks in your current documentation you will need to remove them when you place the documents into a subdirectory so that Jekyll can serve them correctly. - -{% include alert.html type="warning" title="Using permalinks in your archive documentation Front Matter will cause issues with versioning as this effectively 'hardcodes' the url of that page and will break the versioning links. Please be aware!" %} - -## 404 Errors - -There will be times where users will navigate around the documentation and could end up pointing to an invalid page that doesn't exist. For instance while you are reading this page on the **Current** version if you were to change this to the Previous version, via the dropdown, then you will get a page not found as this versioning page did not exist in the prior version. We have created a 404.md page in the base of the site so that the user still gets to navigate even though the page was not found. You can update this page with your own information should you so wish. - -{% include alert.html type="info" title="When pages are not found and the 404 page is displayed the TOC menus default back to links pointing to the current release." %}