This repository contains the common infrastructure for building markdown documentation with Jekyll.
Install Ruby 1.9.x (2.x may or may not work).
Open a terminal or "Git Bash" if on Windows.
cd
to the directory where your markdown documentation repository is.
Add a new git remote to the docs-base repository. This will be used to merge any new features and fixes from the documentation base repository.
git remote add base [email protected]:telerik/docs-base.git
Fetch the "base" remote. This will retrieve the latest files.
git fetch base
Merge the "base/master" branch to your documentation repository branch.
git merge --no-ff base/master
Resolve any conflicts (available via git status
) and commit git commit
. Make sure you don't remove any customizations you have made to some of the base files.
Open the "_config.yml" file and set the baseurl
and url
attributes. The first is used for resolving the path to images and hyperlinks. The second is the online URL of the documentation and is used for creating sitemap.xml
.
url: "http://docs.telerik.com/devtools/ios"
baseurl: "/devtools/ios"
Create a Google Custom Search Engine (or ask one to be created for you). Set the google_custom_search
attribute in "_config.yml". If you forget this step the search results will be from the Kendo UI documentation.
Run bundle install
. If the bundle
command is not found run gem install bundler
. This will install Jekyll and all other required packages.
Run jekyll serve
. After a while jekyll build the documentation and start a web server at http://0.0.0.0:4000/<baseurl>
e.g. http://0.0.0.0:4000/devtools/ios
. You can now view the documentation in your browser.
Exclude the _site
directory from git by adding _site
to your .gitignore
.
Jekyll builds a static HTML site in the _site
directory. This contents of this directory can be deployed on a live server.
Important: Jekyll creates .html pages by default. However the documentation creates links without .html extension. A
web.config
with rewrite rules is included out of the box.
Jekyll is a tool for creating static html web sites. It supports markdown which makes it a good fit for our needs. It is also highly customizable which makes delivering new documentation features a breeze.
Contains common include files used by the layout pages. Not included in the final output in the _site
directory.
The layout pages used by the documentation site. They define the common HTML which contains navigation, search and other common UI. Not included in the final output.
Contains Jekyll plugins (Ruby classes) which are needed for producing the final output. Not included in the final output.
The following plugins are currently available:
web.config
to handle the previous_url
attribute. Contains CSS, JavaScript and image files used by the documentation. Included in the final output.
Any file can be changed per your requirements. However you will have to handle merge conflicts once you need to update to the latest documentation base changes. The following files are likely to be customized:
You can organize your help topics in directories. The directory and filename will determine the final url of your topic. For example getting-started/introduction.md
will lead to getting-started/introduction
Your markdown file must start with the so called "front matter". This is some metadata used by jekyll and the documentation. Here is an example.
---
title: Getting started
page_title: Getting started with Kendo UI
description: Installation and getting started instructions for Kendo UI
position: 0
slug: getting-started
previous_url: /introduction/start
---
The supported attributes are:
Determines the text displayed in the TOC navigation (the treeview in the left).
The contents of the <title>
in the final output. If page_title
is not set the value of title
is usded. Blade name was meta_title
.
Used to set the contents of the <meta name="description">
in the final output. Improves SEO. Blade name was meta_description
.
The position this document will appear at in the TOC navigation. Blade name was ordinal
.
The optional unique identifier of the page. Can be used to link to the current page [Getting-started]({% slug getting-started%})
The previous URL of this page. Used to create IIS redirect rules in web.config
. Supports comma separated values if there is more than one previous url previous_url: /foo/bar, /bar/foo
.
The TOC displays an entry for all directories and files.
The the title
attribute of the markdown file determines the text displayed for that file in the TOC. The position
attribute determines its position in the TOC. If position
is not set the file will appear in its alphabetical order after all directories.
By default directories come before the files which don't have position
set. The directory name determines the text displayed in the TOC. To change it you have to add an entry in _config.yml
under navigation
.
For example we want the introduction/getting-started
directory to appear as Getting Started
in the TOC. Open _config.yml
and find the navigation
attribute. Add a new item:
navigation
-
introduction/getting-started
title: Getting Started
Directories appear alphabetically sorted by default. You can change their position again from _config.yml
.
navigation
-
introduction/getting-started
title: Getting Started
position: 0