|author||James Turton <firstname.lastname@example.org>||Fri Aug 27 12:33:25 2021 +0200|
|committer||James Turton <email@example.com>||Fri Aug 27 12:33:25 2021 +0200|
N.B. As of 2021-08-27, documentation is no longer kept in drill/gh-pages. All documentation, including both the source Markdown and the generated HTML is now kept in this repository.
The Apache Drill website is built by Jekyll from Markdown sources in designated branches of this repository. The build process flows from left to right in the following table.
|Source Markdown branch||Generated HTML branch||Publish URL|
To make documenation contributions easier, pull requests to this repository do not require the creation of JIRA ticket. Nevertheless, a Drill project commiter will still need to check and merge a submitted PR.
When new commits are pushed to any of the listed source Markdown branches, a Jekyll website build will be kicked off. You can monitor the build, which normally runs in about 3 minutes, and view its logs at https://ci2.apache.org/. Once the build completes, the resulting website will automatically be committed to the corresponding HTML branch in the table above. The commit to the HTML branch will result in a deployment to the corresponding publish URL. While it is possible to push commits directly to the HTML branches to effect website updates, it's almost certain that you never want to do this and should be working in one of the Markdown branches.
At the time of writing, the staging website has no designated reponsibility and you may freely use it to test things out without worrying about what you clobber there. Note that this means that others can freely clobber your staging deployments too.
For more extensive documentation contributions it is beneficial to build and serve the website locally.
The documentation pages are placed under
_docs. You can modify existing .md files, or you can create new .md files to add to the Apache Drill documentation site. Create pull requests to submit your documentation updates. The Kramdown Markdown processor employed by Jekyll supports a dialect of Markdown which is a superset of standard Markdown.
If you create new Markdown (.md) files, include the required YAML front matter and name the file using the methods described in this section.
The YAML front matter has three important parameters:
title:- This is the title of the page enclosed in quotation marks. Each page must have a unique title
slug:- Set this to the same value as
title, it will be slugified automatically by Jekyll.
date:- This field is needed for Jekyll to write a last-modified date. Initially, leave this field blank.
parent:- This is the title of the page's parent page. It should be empty for top-level sections/guides, and be identical to the title attribute of another page in all other cases.
The name of the file itself doesn't matter except for the alphanumeric order of the filenames. Files that share the same parent are ordered alphanumerically. Note that the content of parent files is ignored, so add an overview/introduction child when needed.
030-baz.md, etc. This allows room to add files in-between (eg,
...-getting-started-with-drill.md. If you're not sure what the slug is, you should be able to see it in the URL and then adjust (the URLs are auto-generated based on the title attribute).
To preview the website on your local machine:
bundle exec jekyll build bundle exec jekyll serve [--livereload] [--incremental]
Once you‘re happy with the results, commit to the source Markdown branch and push to your fork, or directly to drill-site if you’re a Drill committer.
To automatically add the
last-modified-on date, a one-time local setup is required:
drill/.git/hooks, create a file named
pre-commit(no extension) that contains this script:
#!/bin/sh # Contents of .git/hooks/pre-commit git diff --cached --name-status | grep "^M" | while read a b; do cat $b | sed "/---.*/,/---.*/s/^date:.*$/date: $(date -u "+%Y-%m-%d")/" > tmp mv tmp $b git add $b done
chmod +x pre-commit
On the page you create, in addition to the title, and
parent:, you now need to add
date: to the front matter of any file you create. For example:
--- title: "Configuring Multitenant Resources" parent: "Configuring a Multitenant Cluster" date: ---
Do not fill in or alter the date: field. Jekyll and git take care of that when you commit the file.
Multilingual support was added to the website in June 2021 using the polyglot Jekyll plugin. The fallback language is set to English which means that when a translated page is not available the English version will be shown. This means that a language which is incompletely translated is still deployable with no adverse effects.
lang-codeforthwith) to the
languagesproperty in _config.yml.
lang-code/subdirectory to the root directory.
lang-code/subdirectory to each collection that will be translated, e.g.
exclude_from_localizationlist in _config.yml to ensure that the content you want to translate is not excluded from processing by the multlingual plugin.
The English versions of “site” pages such as index.html are stored in the root directory. Create corresponding translated pages under
lang-code/ in which you set
lang in the front matter to
lang-code and leave the
permalink the same as the English page.
The English versions of “collection” pages such as the markdown under _docs/ are stored in an en/ subdirectory of the collection root. Create corresponding translated pages in the collection under
lang-code/ in which you translate both
parent in the front matter but leave the
slug the same as the English page and set
lang-code. Once you've translated the
title of a parent page, you will need to provide files for each of its children (which can still contain the original English content) and in each set
parent to the translated
title of the parent.