Apache Submarine is using Jekyll which is a static site generator and Github Pages as a site publisher.
For the more details, see help.github.com/articles/about-github-pages-and-jekyll/.
# ruby --version >= 2.0.0 # Install Bundler using gem gem install bundler cd $SUBMARINE_HOME/docs # Install all dependencies declared in the Gemfile bundle install
For the further information about requirements, please see here.
On OS X 10.9, you may need to do
xcode-select --install
If you don't want to encounter uglily rendered pages, run the documentation site in your local first.
In $SUBMARINE_HOME/docs
folder, run
bundle exec jekyll serve --watch
Using the above command, Jekyll will start a web server at http://localhost:4000
and watch the /docs
directory to update.
docs/
folder is organized like below:
docs/ ├── _includes/themes/submarine │ ├── _navigation.html │ └── default.html ├── _layouts ├── _plugins ├── assets/themes/submarine -> {ASSET_PATH} │ ├── bootstrap │ ├── css │ ├── img │ └── js ├── development/ *.md ├── displaysystem/ *.md ├── install/ *.md ├── interpreter/ *.md ├── manual/ *.md ├── quickstart/ *.md ├── rest-api/ *.md ├── security/ *.md ├── storage/ *.md ├── Gemfile ├── Gemfile.lock ├── _config.yml ├── index.md └── ...
_navigation.html
: the dropdown menu in navbardefault.html
& _layouts/
: define default HTML layout_plugins/
: custom plugin *.rb
files can be placed in this folder. See jekyll/plugins for the further information.{ASSET_PATH}/css/style.css
: extra css components can be defined{ASSET_PATH}/img/docs-img/
: image files used for document pages can be placed in this folder{ASSET_PATH}/js/
: extra .js
files can be placedGemfile
: defines bundle dependencies. They will be installed by bundle install
.Gemfile.lock
: when you run bundle install
, bundler will persist all gems name and their version to this file. For the more details, see Bundle “The Gemfile Lock”documentation_group
: development/
, displaysystem/
, install/
, interpreter/
..._config.yml
: defines configuration options for docs website. See jekyll/configuration for the other available config variables.index.md
: the main page of http://submarine.apache.org/docs/<SUBMARINE_VERSION>/
Submarine documentation pages are written with Markdown. It is possible to use GitHub flavored syntax and intermix plain HTML.
Every page contains YAML front matter block in their header. Don‘t forget to wrap the front matter list with triple-dashed lines(---
) like below. The document page should start this triple-dashed lines. Or you will face 404 error, since Jekyll can’t find the page.
--- layout: page title: "Apache Submarine Tutorial" description: "This tutorial page contains a short walk-through tutorial that uses Apache Spark backend. Please note that this tutorial is valid for Spark 1.3 and higher." group: quickstart ---
layout
: the default layout is page
which is defined in _layout/page.html
.title
: the title for the document. Please note that if it needs to include Submarine
, it should be Apache Submarine
, not Submarine
.description
: a short description for the document. One or two sentences would be enough. This description also will be shown as an extract sentence when people search pages.group
: a category for the document page, more than on group can be applied by using this syntax:group: - group1 - group2
All documents are structured with headings. From these headings, you can automatically generate a Table of Contents. There is a simple rule for Submarine docs headings.
# Level-1 heading <- used only for the main title ## Level-2 heading <- start with this ### Level-3 heading #### Level-4 heading <- won't be converted in TOC from this level
<div id="toc"></div>
Add this line below # main title
in order to generate a Table of Contents.
Headings until ### (Level-3 heading)
are included to TOC.
Default setting options for TOC are definded in here.
If you're going to create new pages, there are some spots you need to add the location of the page.
SUBMARINE_VERSION
and BASE_PATH
property in _config.yml
generate static website in ./_site
# go to /docs under Submarine source JEKYLL_ENV=production bundle exec jekyll build
checkout ASF repo
svn co https://svn.apache.org/repos/asf/submarine asf-submarine
copy submarine/docs/_site
to asf-submarine/site/docs/[VERSION]
svn commit