diff --git a/README.md b/README.md
index 2378c0a58..873359eb5 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,7 @@ this is how Turnilo emerged.
* Unified view for historical and real-time data.
* Blazingly fast.
-
+
## Try it!
@@ -206,24 +206,11 @@ You can find more infrmation [here](https://www.jetbrains.com/help/webstorm/runn
* [Ruby](https://www.ruby-lang.org/en/documentation/installation/)
* [Bundler](https://bundler.io)
-Go to docs directory.
-
-```
-cd docs
-```
-
-Install dependencies.
-
-```
-bundle install
-```
-
-Run your Jekyll site locally and open [http://localhost:4000/](http://localhost:4000/)
-
-```
-bundle exec jekyll serve --incremental
-```
+Go to the docs folder and:
+1. Install `bundle install` or `update bundle` update dependencies
+2. Run `bundle exec jekyll serve --livereload`
+3. Open [http://localhost:4000/](http://localhost:4000/)
## License
diff --git a/docs/Gemfile b/docs/Gemfile
index 4569262df..03455cb7c 100644
--- a/docs/Gemfile
+++ b/docs/Gemfile
@@ -1 +1,3 @@
-gem 'github-pages', '212', group: :jekyll_plugins
+source "https://rubygems.org"
+
+gem 'github-pages', '~> 227', group: :jekyll_plugins
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
index fb9e113c3..2142b45ef 100644
--- a/docs/Gemfile.lock
+++ b/docs/Gemfile.lock
@@ -1,95 +1,95 @@
GEM
+ remote: https://rubygems.org/
specs:
- activesupport (6.0.3.5)
+ activesupport (6.0.6)
concurrent-ruby (~> 1.0, >= 1.0.2)
i18n (>= 0.7, < 2)
minitest (~> 5.1)
tzinfo (~> 1.1)
zeitwerk (~> 2.2, >= 2.2.2)
- addressable (2.7.0)
- public_suffix (>= 2.0.2, < 5.0)
+ addressable (2.8.1)
+ public_suffix (>= 2.0.2, < 6.0)
coffee-script (2.4.1)
coffee-script-source
execjs
coffee-script-source (1.11.1)
colorator (1.1.0)
- commonmarker (0.17.13)
- ruby-enum (~> 0.5)
- concurrent-ruby (1.1.8)
- dnsruby (1.61.5)
+ commonmarker (0.23.6)
+ concurrent-ruby (1.1.10)
+ dnsruby (1.61.9)
simpleidn (~> 0.1)
- em-websocket (0.5.2)
+ em-websocket (0.5.3)
eventmachine (>= 0.12.9)
- http_parser.rb (~> 0.6.0)
- ethon (0.12.0)
- ffi (>= 1.3.0)
+ http_parser.rb (~> 0)
+ ethon (0.15.0)
+ ffi (>= 1.15.0)
eventmachine (1.2.7)
- execjs (2.7.0)
- faraday (1.3.0)
- faraday-net_http (~> 1.0)
- multipart-post (>= 1.2, < 3)
- ruby2_keywords
- faraday-net_http (1.0.1)
- ffi (1.15.0)
+ execjs (2.8.1)
+ faraday (2.6.0)
+ faraday-net_http (>= 2.0, < 3.1)
+ ruby2_keywords (>= 0.0.4)
+ faraday-net_http (3.0.1)
+ ffi (1.15.5)
forwardable-extended (2.6.0)
gemoji (3.0.1)
- github-pages (212)
- github-pages-health-check (= 1.17.0)
- jekyll (= 3.9.0)
+ github-pages (227)
+ github-pages-health-check (= 1.17.9)
+ jekyll (= 3.9.2)
jekyll-avatar (= 0.7.0)
jekyll-coffeescript (= 1.1.1)
- jekyll-commonmark-ghpages (= 0.1.6)
+ jekyll-commonmark-ghpages (= 0.2.0)
jekyll-default-layout (= 0.1.4)
jekyll-feed (= 0.15.1)
jekyll-gist (= 1.5.0)
jekyll-github-metadata (= 2.13.0)
+ jekyll-include-cache (= 0.2.1)
jekyll-mentions (= 1.6.0)
jekyll-optional-front-matter (= 0.3.2)
jekyll-paginate (= 1.1.0)
jekyll-readme-index (= 0.3.0)
jekyll-redirect-from (= 0.16.0)
jekyll-relative-links (= 0.6.1)
- jekyll-remote-theme (= 0.4.2)
+ jekyll-remote-theme (= 0.4.3)
jekyll-sass-converter (= 1.5.2)
- jekyll-seo-tag (= 2.7.1)
+ jekyll-seo-tag (= 2.8.0)
jekyll-sitemap (= 1.4.0)
jekyll-swiss (= 1.0.0)
- jekyll-theme-architect (= 0.1.1)
- jekyll-theme-cayman (= 0.1.1)
- jekyll-theme-dinky (= 0.1.1)
- jekyll-theme-hacker (= 0.1.2)
- jekyll-theme-leap-day (= 0.1.1)
- jekyll-theme-merlot (= 0.1.1)
- jekyll-theme-midnight (= 0.1.1)
- jekyll-theme-minimal (= 0.1.1)
- jekyll-theme-modernist (= 0.1.1)
- jekyll-theme-primer (= 0.5.4)
- jekyll-theme-slate (= 0.1.1)
- jekyll-theme-tactile (= 0.1.1)
- jekyll-theme-time-machine (= 0.1.1)
+ jekyll-theme-architect (= 0.2.0)
+ jekyll-theme-cayman (= 0.2.0)
+ jekyll-theme-dinky (= 0.2.0)
+ jekyll-theme-hacker (= 0.2.0)
+ jekyll-theme-leap-day (= 0.2.0)
+ jekyll-theme-merlot (= 0.2.0)
+ jekyll-theme-midnight (= 0.2.0)
+ jekyll-theme-minimal (= 0.2.0)
+ jekyll-theme-modernist (= 0.2.0)
+ jekyll-theme-primer (= 0.6.0)
+ jekyll-theme-slate (= 0.2.0)
+ jekyll-theme-tactile (= 0.2.0)
+ jekyll-theme-time-machine (= 0.2.0)
jekyll-titles-from-headings (= 0.5.3)
jemoji (= 0.12.0)
- kramdown (= 2.3.0)
+ kramdown (= 2.3.2)
kramdown-parser-gfm (= 1.1.0)
liquid (= 4.0.3)
mercenary (~> 0.3)
minima (= 2.5.1)
- nokogiri (>= 1.10.4, < 2.0)
+ nokogiri (>= 1.13.6, < 2.0)
rouge (= 3.26.0)
terminal-table (~> 1.4)
- github-pages-health-check (1.17.0)
+ github-pages-health-check (1.17.9)
addressable (~> 2.3)
dnsruby (~> 1.60)
octokit (~> 4.0)
- public_suffix (>= 2.0.2, < 5.0)
+ public_suffix (>= 3.0, < 5.0)
typhoeus (~> 1.3)
- html-pipeline (2.14.0)
+ html-pipeline (2.14.3)
activesupport (>= 2)
nokogiri (>= 1.4)
- http_parser.rb (0.6.0)
+ http_parser.rb (0.8.0)
i18n (0.9.5)
concurrent-ruby (~> 1.0)
- jekyll (3.9.0)
+ jekyll (3.9.2)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
@@ -107,12 +107,12 @@ GEM
jekyll-coffeescript (1.1.1)
coffee-script (~> 2.2)
coffee-script-source (~> 1.11.1)
- jekyll-commonmark (1.3.1)
- commonmarker (~> 0.14)
- jekyll (>= 3.7, < 5.0)
- jekyll-commonmark-ghpages (0.1.6)
- commonmarker (~> 0.17.6)
- jekyll-commonmark (~> 1.2)
+ jekyll-commonmark (1.4.0)
+ commonmarker (~> 0.22)
+ jekyll-commonmark-ghpages (0.2.0)
+ commonmarker (~> 0.23.4)
+ jekyll (~> 3.9.0)
+ jekyll-commonmark (~> 1.4.0)
rouge (>= 2.0, < 4.0)
jekyll-default-layout (0.1.4)
jekyll (~> 3.0)
@@ -123,6 +123,8 @@ GEM
jekyll-github-metadata (2.13.0)
jekyll (>= 3.4, < 5.0)
octokit (~> 4.0, != 4.4.0)
+ jekyll-include-cache (0.2.1)
+ jekyll (>= 3.7, < 5.0)
jekyll-mentions (1.6.0)
html-pipeline (~> 2.3)
jekyll (>= 3.7, < 5.0)
@@ -135,57 +137,57 @@ GEM
jekyll (>= 3.3, < 5.0)
jekyll-relative-links (0.6.1)
jekyll (>= 3.3, < 5.0)
- jekyll-remote-theme (0.4.2)
+ jekyll-remote-theme (0.4.3)
addressable (~> 2.0)
jekyll (>= 3.5, < 5.0)
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
rubyzip (>= 1.3.0, < 3.0)
jekyll-sass-converter (1.5.2)
sass (~> 3.4)
- jekyll-seo-tag (2.7.1)
+ jekyll-seo-tag (2.8.0)
jekyll (>= 3.8, < 5.0)
jekyll-sitemap (1.4.0)
jekyll (>= 3.7, < 5.0)
jekyll-swiss (1.0.0)
- jekyll-theme-architect (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-architect (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-cayman (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-cayman (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-dinky (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-dinky (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-hacker (0.1.2)
+ jekyll-theme-hacker (0.2.0)
jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-leap-day (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-leap-day (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-merlot (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-merlot (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-midnight (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-midnight (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-minimal (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-minimal (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-modernist (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-modernist (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-primer (0.5.4)
+ jekyll-theme-primer (0.6.0)
jekyll (> 3.5, < 5.0)
jekyll-github-metadata (~> 2.9)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-slate (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-slate (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-tactile (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-tactile (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
- jekyll-theme-time-machine (0.1.1)
- jekyll (~> 3.5)
+ jekyll-theme-time-machine (0.2.0)
+ jekyll (> 3.5, < 5.0)
jekyll-seo-tag (~> 2.0)
jekyll-titles-from-headings (0.5.3)
jekyll (>= 3.3, < 5.0)
@@ -195,12 +197,12 @@ GEM
gemoji (~> 3.0)
html-pipeline (~> 2.2)
jekyll (>= 3.0, < 5.0)
- kramdown (2.3.0)
+ kramdown (2.3.2)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.3)
- listen (3.4.1)
+ listen (3.7.1)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.3.6)
@@ -208,35 +210,34 @@ GEM
jekyll (>= 3.5, < 5.0)
jekyll-feed (~> 0.9)
jekyll-seo-tag (~> 2.1)
- minitest (5.13.0)
- multipart-post (2.1.1)
- nokogiri (1.11.1-x86_64-darwin)
+ minitest (5.16.3)
+ nokogiri (1.13.8-arm64-darwin)
+ racc (~> 1.4)
+ nokogiri (1.13.8-x86_64-darwin)
racc (~> 1.4)
- octokit (4.20.0)
- faraday (>= 0.9)
- sawyer (~> 0.8.0, >= 0.5.3)
+ octokit (4.25.1)
+ faraday (>= 1, < 3)
+ sawyer (~> 0.9)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
- public_suffix (4.0.6)
- racc (1.4.16)
- rb-fsevent (0.10.4)
+ public_suffix (4.0.7)
+ racc (1.6.0)
+ rb-fsevent (0.11.2)
rb-inotify (0.10.1)
ffi (~> 1.0)
- rexml (3.2.3)
+ rexml (3.2.5)
rouge (3.26.0)
- ruby-enum (0.9.0)
- i18n
- ruby2_keywords (0.0.4)
- rubyzip (2.3.0)
+ ruby2_keywords (0.0.5)
+ rubyzip (2.3.2)
safe_yaml (1.0.5)
sass (3.7.4)
sass-listen (~> 4.0.0)
sass-listen (4.0.0)
rb-fsevent (~> 0.9, >= 0.9.4)
rb-inotify (~> 0.9, >= 0.9.7)
- sawyer (0.8.2)
+ sawyer (0.9.2)
addressable (>= 2.3.5)
- faraday (> 0.8, < 2.0)
+ faraday (>= 0.17.3, < 3)
simpleidn (0.2.1)
unf (~> 0.1.4)
terminal-table (1.8.0)
@@ -244,19 +245,20 @@ GEM
thread_safe (0.3.6)
typhoeus (1.4.0)
ethon (>= 0.9.0)
- tzinfo (1.2.9)
+ tzinfo (1.2.10)
thread_safe (~> 0.1)
unf (0.1.4)
unf_ext
- unf_ext (0.0.7.7)
- unicode-display_width (1.7.0)
- zeitwerk (2.4.2)
+ unf_ext (0.0.8.2)
+ unicode-display_width (1.8.0)
+ zeitwerk (2.6.1)
PLATFORMS
+ arm64-darwin-21
x86_64-darwin-19
DEPENDENCIES
- github-pages (= 212)
+ github-pages (~> 227)
BUNDLED WITH
- 2.2.14
+ 2.3.22
diff --git a/docs/_config.yml b/docs/_config.yml
index 2e3260681..d319276ca 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -1,14 +1,38 @@
-theme: jekyll-theme-minimal
+title: "Turnilo documentation"
+url: https://allegro.github.io/turnilo/
+logo: assets/images/turnilo-logo.png
+footer_content: "Copyright © 2017-2022 Allegro.pl"
-markdown: kramdown
+remote_theme: just-the-docs/just-the-docs
-kramdown:
- toc_levels: 2..6
- input: GFM
+# color configuration for {: .note } and {: .important }
+callouts:
+ note:
+ color: blue
+ important:
+ color: red
-plugins:
- - jemoji
+# enable mermaid graphs
+mermaid:
+ version: "9.1.7"
-title: Turnilo
-logo: images/turnilo-logo.png
-show_downloads: false
+# enable footer link for easy navigation to the top of the page
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# enable footer link to the GitHub editor for the page
+gh_edit_link: true
+gh_edit_repository: https://github.com/allegro/turnilo
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_source: "docs"
+gh_edit_branch: "master"
+gh_edit_view_mode: "edit"
+
+
+# header links
+aux_links:
+ "Application demo":
+ - "https://turnilo.app"
+ "Project history":
+ - "https://blog.allegro.tech/2018/10/turnilo-lets-change-the-way-people-explore-big-data.html"
+aux_links_new_tab: true
diff --git a/docs/_includes/toc.html b/docs/_includes/toc.html
new file mode 100644
index 000000000..3cff42f11
--- /dev/null
+++ b/docs/_includes/toc.html
@@ -0,0 +1,182 @@
+{% capture tocWorkspace %}
+ {% comment %}
+ Copyright (c) 2017 Vladimir "allejo" Jimenez
+
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.
+ {% endcomment %}
+ {% comment %}
+ Version 1.2.0
+ https://github.com/allejo/jekyll-toc
+
+ "...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe
+
+ Usage:
+ {% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %}
+
+ Parameters:
+ * html (string) - the HTML of compiled markdown generated by kramdown in Jekyll
+
+ Optional Parameters:
+ * sanitize (bool) : false - when set to true, the headers will be stripped of any HTML in the TOC
+ * class (string) : '' - a CSS class assigned to the TOC
+ * id (string) : '' - an ID to assigned to the TOC
+ * h_min (int) : 1 - the minimum TOC header level to use; any header lower than this value will be ignored
+ * h_max (int) : 6 - the maximum TOC header level to use; any header greater than this value will be ignored
+ * ordered (bool) : false - when set to true, an ordered list will be outputted instead of an unordered list
+ * item_class (string) : '' - add custom class(es) for each list item; has support for '%level%' placeholder, which is the current heading level
+ * submenu_class (string) : '' - add custom class(es) for each child group of headings; has support for '%level%' placeholder which is the current "submenu" heading level
+ * base_url (string) : '' - add a base url to the TOC links for when your TOC is on another page than the actual content
+ * anchor_class (string) : '' - add custom class(es) for each anchor element
+ * skip_no_ids (bool) : false - skip headers that do not have an `id` attribute
+
+ Output:
+ An ordered or unordered list representing the table of contents of a markdown block. This snippet will only
+ generate the table of contents and will NOT output the markdown given to it
+ {% endcomment %}
+
+ {% capture newline %}
+ {% endcapture %}
+ {% assign newline = newline | rstrip %}
+
+ {% capture deprecation_warnings %}{% endcapture %}
+
+ {% if include.baseurl %}
+ {% capture deprecation_warnings %}{{ deprecation_warnings }}{{ newline }}{% endcapture %}
+ {% endif %}
+
+ {% if include.skipNoIDs %}
+ {% capture deprecation_warnings %}{{ deprecation_warnings }}{{ newline }}{% endcapture %}
+ {% endif %}
+
+ {% capture jekyll_toc %}{% endcapture %}
+ {% assign orderedList = include.ordered | default: false %}
+ {% assign baseURL = include.base_url | default: include.baseurl | default: '' %}
+ {% assign skipNoIDs = include.skip_no_ids | default: include.skipNoIDs | default: false %}
+ {% assign minHeader = include.h_min | default: 1 %}
+ {% assign maxHeader = include.h_max | default: 6 %}
+ {% assign nodes = include.html | strip | split: ' maxHeader %}
+ {% continue %}
+ {% endif %}
+
+ {% assign _workspace = node | split: '' | first }}>{% endcapture %}
+ {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+
+ {% if include.item_class and include.item_class != blank %}
+ {% capture listItemClass %} class="{{ include.item_class | replace: '%level%', currLevel | split: '.' | join: ' ' }}"{% endcapture %}
+ {% endif %}
+
+ {% if include.submenu_class and include.submenu_class != blank %}
+ {% assign subMenuLevel = currLevel | minus: 1 %}
+ {% capture subMenuClass %} class="{{ include.submenu_class | replace: '%level%', subMenuLevel | split: '.' | join: ' ' }}"{% endcapture %}
+ {% endif %}
+
+ {% capture anchorBody %}{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}{% endcapture %}
+
+ {% if htmlID %}
+ {% capture anchorAttributes %} href="{% if baseURL %}{{ baseURL }}{% endif %}#{{ htmlID }}"{% endcapture %}
+
+ {% if include.anchor_class %}
+ {% capture anchorAttributes %}{{ anchorAttributes }} class="{{ include.anchor_class | split: '.' | join: ' ' }}"{% endcapture %}
+ {% endif %}
+
+ {% capture listItem %}{{ anchorBody }}{% endcapture %}
+ {% elsif skipNoIDs == true %}
+ {% continue %}
+ {% else %}
+ {% capture listItem %}{{ anchorBody }}{% endcapture %}
+ {% endif %}
+
+ {% if currLevel > lastLevel %}
+ {% capture jekyll_toc %}{{ jekyll_toc }}<{{ listModifier }}{{ subMenuClass }}>{% endcapture %}
+ {% elsif currLevel < lastLevel %}
+ {% assign repeatCount = lastLevel | minus: currLevel %}
+
+ {% for i in (1..repeatCount) %}
+ {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %}
+ {% endfor %}
+
+ {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %}
+ {% else %}
+ {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %}
+ {% endif %}
+
+ {% capture jekyll_toc %}{{ jekyll_toc }}{{ listItem }}{% endcapture %}
+
+ {% assign lastLevel = currLevel %}
+ {% assign firstHeader = false %}
+ {% endfor %}
+
+ {% assign repeatCount = minHeader | minus: 1 %}
+ {% assign repeatCount = lastLevel | minus: repeatCount %}
+ {% for i in (1..repeatCount) %}
+ {% capture jekyll_toc %}{{ jekyll_toc }}{% endcapture %}
+ {% endfor %}
+
+ {% if jekyll_toc != '' %}
+ {% assign rootAttributes = '' %}
+ {% if include.class and include.class != blank %}
+ {% capture rootAttributes %} class="{{ include.class | split: '.' | join: ' ' }}"{% endcapture %}
+ {% endif %}
+
+ {% if include.id and include.id != blank %}
+ {% capture rootAttributes %}{{ rootAttributes }} id="{{ include.id }}"{% endcapture %}
+ {% endif %}
+
+ {% if rootAttributes %}
+ {% assign nodes = jekyll_toc | split: '>' %}
+ {% capture jekyll_toc %}<{{ listModifier }}{{ rootAttributes }}>{{ nodes | shift | join: '>' }}>{% endcapture %}
+ {% endif %}
+ {% endif %}
+{% endcapture %}{% assign tocWorkspace = '' %}{{ deprecation_warnings }}{{ jekyll_toc -}}
diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html
new file mode 100644
index 000000000..0166be5c5
--- /dev/null
+++ b/docs/_layouts/page.html
@@ -0,0 +1,6 @@
+---
+layout: default
+---
+
+{% include toc.html html=content %}
+{{ content }}
diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
deleted file mode 100644
index f0dc51651..000000000
--- a/docs/assets/css/style.scss
+++ /dev/null
@@ -1,13 +0,0 @@
----
----
-
-@import "{{ site.theme }}";
-
-@media screen and (min-width: 1350px) {
- .wrapper {
- width: 1280px;
- }
- .wrapper section {
- width: 960px;
- }
-}
diff --git a/docs/images/showcase.gif b/docs/assets/images/showcase.gif
similarity index 100%
rename from docs/images/showcase.gif
rename to docs/assets/images/showcase.gif
diff --git a/docs/images/turnilo-logo.png b/docs/assets/images/turnilo-logo.png
similarity index 100%
rename from docs/images/turnilo-logo.png
rename to docs/assets/images/turnilo-logo.png
diff --git a/docs/configuration-cluster.md b/docs/configuration-cluster.md
index 0f2fd89d0..6324faf34 100644
--- a/docs/configuration-cluster.md
+++ b/docs/configuration-cluster.md
@@ -1,7 +1,8 @@
-# Configuring Turnilo
-
-* TOC
-{:toc}
+---
+title: Configuration - cluster
+nav_order: 2
+layout: page
+---
## Overview
@@ -90,8 +91,8 @@ Should the server trust the `X-Forwarded-*` headers. If "always", Turnilo will
Specify that Turnilo should set the [StrictTransportSecurity](https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security) header.
-Note that Turnilo can itself only run an http server.
-This option is intended to be used when when Turnilo is running behind a HTTPS terminator like AWS ELB.
+Note that Turnilo can itself only run a http server.
+This option is intended to be used when Turnilo is running behind an HTTPS terminator like AWS ELB.
## Configuring the Clusters
@@ -131,7 +132,7 @@ The timeout to set on the Druid queries in ms. See [documentation](https://druid
**retry** (object)
Options for retries on Druid native queries. If no object is provided Turnilo will not retry failed queries.
-Object should have following structure:
+Object should have the following structure:
```yaml
retry:
diff --git a/docs/configuration-customizations.md b/docs/configuration-customizations.md
index a16ee8558..8d0ce5aa5 100644
--- a/docs/configuration-customizations.md
+++ b/docs/configuration-customizations.md
@@ -1,7 +1,8 @@
-# Customization
-
-* TOC
-{:toc}
+---
+title: Configuration - customization
+nav_order: 4
+layout: page
+---
## Overview
@@ -76,7 +77,7 @@ customization:
These custom links will appear in the share menu.
-By default, external views are opened in a new tab but you can disable this by setting `sameWindow: true`
+By default, external views are opened in a new tab, but you can disable this by setting `sameWindow: true`
## Timezones
diff --git a/docs/configuration-datacubes.md b/docs/configuration-datacubes.md
index 2669ab19b..ad51376e6 100644
--- a/docs/configuration-datacubes.md
+++ b/docs/configuration-datacubes.md
@@ -1,7 +1,8 @@
-# Configuring Data Cubes
-
-* TOC
-{:toc}
+---
+title: Configuration - data cubes
+nav_order: 3
+layout: page
+---
## Overview
@@ -25,7 +26,7 @@ The user visible name that will be used to describe this data cube in the UI. It
**description** (markdown)
-The description of the data cube in markdown format. Description is shown on home page.
+The description of the data cube in Markdown format. Description is shown on home page.
If description contains horizontal line (markdown: ` --- `) it will split description and
later part will be visible after clicking "Show more" button on UI.
@@ -70,7 +71,7 @@ A filter defined as [Plywood expression](https://plywood.imply.io/expressions) t
**refreshRule**
-Refresh rule defining how the information about latest data in a data source is obtained.
+Refresh rule defining how the information about the latest data in a data source is obtained.
**maxSplits** (number)
@@ -82,14 +83,14 @@ Number of queries that can be issued to druid. Defaults to 500.
## Refresh rules
-The `refreshRule:` section of the data cube allows the customisation of latest data discovery mechanism.
+The `refreshRule:` section of the data cube allows the customisation of the latest data discovery mechanism.
**rule** ("query" \| "realtime" \| "fixed" ), default: "query"
The name of the rule which will be used to obtain information about the latest data. Following rules are available:
- `query`: best suited for batch data sources. The data source will be queried every minute to obtain the maximum value from time dimension.
-- `realtime`: best suited for realtime data sources. The data source will not be queried and the value of *now* is assumed as a latest data time.
+- `realtime`: best suited for realtime data sources. The data source will not be queried and the value of *now* is assumed as the latest data time.
- `fixed`: best suited for constant data sources. The data source will not be queried and the value of `refreshRule.time` property will be used.
**time** (string - date with time instant)
@@ -134,7 +135,7 @@ You should add:
To the `attributeOverrides` to tell Turnilo that this is numeric.
-You can now use `$age` in numeric expressions. For example you could create a dimension with the formula
+You can now use `$age` in numeric expressions. For example, you could create a dimension with the formula
`$age / 2 + 7`.
@@ -168,7 +169,7 @@ The description of the dimension in the UI. Accepts Markdown format.
**url** (string)
-A url associated with the dimension, with optional token '%s' that is replaced by the dimension value to generate
+An url associated with the dimension, with optional token '%s' that is replaced by the dimension value to generate
a link specific to each value.
**granularities** (string[5] or number[5]), default: ["PT1M", "PT5M", "PT1H", "P1D", "P1W"]`
@@ -187,7 +188,7 @@ For number dimensions you can just provide 5 bucket sizes as integers.
**bucketingStrategy** ("defaultBucket" \| "defaultNoBucket")
-Specify whether or not the dimension should be bucketed by default. If unspecified defaults to 'defaultBucket' for time and numeric dimensions.
+Specify whether the dimension should be bucketed by default. If unspecified defaults to 'defaultBucket' for time and numeric dimensions.
**sortStrategy** ("self" \| `someMeasureName`)
@@ -204,7 +205,7 @@ Set to true if dimension holds multiple values. [Druid Multi-Value Dimensions](h
**formula** (string - plywood expression)
The [Plywood expression](https://plywood.imply.io/expressions) for this dimension.
-By default it is `$name` where *name* is the name of the dimension.
+By default, it is `$name` where *name* is the name of the dimension.
You can create derived dimensions by using non-trivial formulas.
Here are some common use cases for derived dimensions:
@@ -262,18 +263,18 @@ Now my account would represent a custom filter boolean dimension.
#### Quantiles
If you have dimension defined as histogram, you can add quantile measure. Use plywood method quantile on desired histogram and provide required parameters.
-Percentile parameter would be used as default percentile and could be adjusted on UI. Tunning parameters will be passed as is to Druid.
+Percentile parameter would be used as default percentile and could be adjusted on UI. Tuning parameters will be passed as is to Druid.
```yaml
- name: clicks_percentile
formula: $main.quantile($response_time_ms, 0.99, 'k=128')
```
-Turnilo can handle percentiles only as top level operation in expression so it is impossible to nest quantile expression inside let's say division.
+Turnilo can handle percentiles only as top level operation in expression, so it is impossible to nest quantile expression inside let's say division.
```yaml
- name: opaque_percentile_formula
- forumla: $main.quantile($response_time_ms, 0.9, 'k=128') * 1000
+ formula: $main.quantile($response_time_ms, 0.9, 'k=128') * 1000
```
If turnilo encounters such formula, it would assume it is simple measure. User would be able to use this measure as is, but won't be able to picking percentile.
@@ -283,7 +284,7 @@ If turnilo encounters such formula, it would assume it is simple measure. User w
If no existing plywood function meets your needs, you could also define your own custom transformation.
The transformation could be any supported [Druid extraction function](https://druid.apache.org/docs/latest/querying/dimensionspecs.html).
-For example you could apply any number of javascript functions to a string.
+For example, you could apply any number of javascript functions to a string.
To use that in Turnilo define following `options` at data cube level:
@@ -365,7 +366,8 @@ Default format for measure as string in [numbro format](https://numbrojs.com/old
**formula** (string - plywood expression)
-The [Plywood expression](https://plywood.imply.io/expressions) for this dimension. By default it is `$main.sum($name)` where *name* is the name of the measure.
+The [Plywood expression](https://plywood.imply.io/expressions) for this dimension.
+By default, it is `$main.sum($name)` where *name* is the name of the measure.
The `$main` part of the measure expressions serves as a placeholder for the data segment.
In Plywood every aggregate is a function that acts on a data segment.
@@ -386,8 +388,8 @@ One can also create derived measures by using non-trivial expressions in **formu
Ratios are generally considered fun.
```yaml
-- name: ecpm
- title: eCPM
+- name: cpm
+ title: CPM
formula: $main.sum($revenue) / $main.sum($impressions) * 1000
```
@@ -447,12 +449,12 @@ This functionality can be used to access any custom aggregations that might be l
#### Switching metric columns
-If you switch how you ingest you underlying metric and can't (or do not want to) recalculate all of the previous data,
+If you switch how you ingest you underlying metric and can't (or do not want to) recalculate all the previous data,
you could use a derived measure to seemly merge these two metrics in the UI.
Let's say you had a metric called `revenue_in_dollars` and for some reason you will now be ingesting it as `revenue_in_cents`.
-Furthermore right now your users are using Turnilo with the measure:
+Furthermore, right now your users are using Turnilo with the measure:
```yaml
- name: revenue
@@ -471,7 +473,7 @@ If your data had a 'clean break' where all events have ether `revenue_in_dollars
If instead there was a period where you were ingesting both metrics then the above solution would double count that interval.
You can 'splice' these two metrics together at a specific time point.
-Logically you should be able leverage the [Filtered aggregations](#filtered-aggregations-formula) to do:
+Logically you should be able to leverage the [Filtered aggregations](#filtered-aggregations-formula) to do:
```yaml
- name: revenue # DO NOT DO THIS IT WILL NOT WORK WITH DRUID < 0.9.2
@@ -483,7 +485,7 @@ Logically you should be able leverage the [Filtered aggregations](#filtered-aggr
But the above will not work because, as of this writing, [Druid can not filter on time in measures](https://github.com/druid-io/druid/issues/2816).
-Instead you can leverage [Custom aggregations](#custom-aggregations) and the `javascript` aggregation to achieve essentially the same thing:
+Instead, you can leverage [Custom aggregations](#custom-aggregations) and the `javascript` aggregation to achieve essentially the same thing:
```yaml
# Add this to the data cube options
@@ -546,7 +548,7 @@ Custom dimension transformations definition. See [custom transformations](#custo
**druidContext**
-Context to be send to Druid with every query executed on the data cube defined as yaml key / value mappings.
+Context to be sent to Druid with every query executed on the data cube defined as yaml key / value mappings.
See [Druid context](https://druid.apache.org/docs/latest/querying/query-context.html).
Advanced options example:
diff --git a/docs/extending-turnilo.md b/docs/extending-turnilo.md
index ceb0f18fa..ac08b787e 100644
--- a/docs/extending-turnilo.md
+++ b/docs/extending-turnilo.md
@@ -1,7 +1,8 @@
-# Extending Turnilo
-
-* TOC
-{:toc}
+---
+title: Extending Turnilo
+nav_order: 8
+layout: page
+---
## Overview
@@ -60,11 +61,11 @@ exports.druidRequestDecoratorFactory = function (logger, params) {
};
```
-You can find this example with additional comments and example config in the [./example](./example/request-decoration) folder.
+You can find this example with additional comments and example config in the [example](example/request-decoration) folder.
This would result in all Druid requests being tagged as:
-
+
## Query decorator
@@ -112,7 +113,7 @@ You need to add your plugin as entry under `plugins` field.
Plugin need to have two fields:
- `name` - name for debug purposes
- `path` - path to the js file
-It can define additional field `settings`. Content of this field would be passed to plugin so it is good place for additional parameters.
+It can define additional field `settings`. Content of this field would be passed to plugin, so it is good place for additional parameters.
```yaml
plugins:
diff --git a/docs/generating-links.md b/docs/generating-links.md
index c043af481..229f078b5 100644
--- a/docs/generating-links.md
+++ b/docs/generating-links.md
@@ -1,10 +1,16 @@
-# Generating Turnilo links
+---
+title: Generating links
+nav_order: 5
+layout: page
+---
+
+## Overview
If you want to generate links pointing to Turnilo's view from external systems you can do so by posting
view definition to `/mkurl` or `/mkurl` endpoint and appending returned `hash` property
to the base URI of Turnilo instance.
-The view definition can be acquired by clicking "Display view definition" in the settings menu at the top-right corner.
+The view definition can be acquired by clicking "Display view definition" in the settings menu in the top-right corner.
The post body must include 3 keys:
@@ -18,14 +24,14 @@ The version of the view definition passed for url generation. Currently supporte
**viewDefinition** (ViewDefinition3 \| Essence)
-The JSON view definition that describes the state of the Turnilo view. Currently the latest and greatest view definition
+The JSON view definition that describes the state of the Turnilo view. Currently, the latest and greatest view definition
structure is "ViewDefinition4". Be aware that older versions are kept for backwards compatibility only and will be
removed at some point.
-# Examples
+## Examples
Here are a few examples that you can try out by yourself.
-All the examples run on the built in example dataset that comes with Turnilo.
+All the examples run on the built-in example dataset that comes with Turnilo.
To follow along please start Turnilo in `--examples` mode like so:
@@ -50,7 +56,7 @@ curl -X POST --header "Content-Type:application/json" --data '
Returned `hash` property value needs to be appended to `http://localhost:9090/` base URI in this example instance
to produce a complete URI.
-## Example 1
+### Example 1
Here is an example that will show the `totals` visualization filtered on `2015-09-10Z` - `2015-09-20Z` with `count` and `added` metrics selected,
the `page` dimension pinned.
@@ -95,11 +101,11 @@ Posting this will produce:
```
-## Example 2
+### Example 2
Here is an example that will display the `line-chart` visualization filtered on: the last 1 day of data (`P1D`),
comment lengths not between 20 and 30, and city name being one of "London" or "Rome", split on `channel`
-and `time` (bucketed by hour - `PT1H`) with `count` measure selected. Additionally Is Robot dimension is pinned,
+and `time` (bucketed by hour - `PT1H`) with `count` measure selected. Additionally, "Is Robot" dimension is pinned,
channels: "en" and "it" are the only visible plots on a line chart and a period between 12pm and 1pm
is highlighted on a graph.
diff --git a/docs/health-checking.md b/docs/health-checking.md
index 6bde2f8f4..c8fbacd2f 100644
--- a/docs/health-checking.md
+++ b/docs/health-checking.md
@@ -1,4 +1,10 @@
-# Checking health of Turnilo instance
+---
+title: Health checking
+nav_order: 6
+layout: page
+---
+
+## Overview
Turnilo instance's health is defined in terms of being able to communicate with all configured Druid brokers
and those brokers knowing about all segments in Zookeeper.
@@ -14,7 +20,7 @@ individually defined cluster timeout (`healthCheckTimeout` property in [cluster
and that the response body contains `inventoryInitialized` flag set to `true`.
If any of the requests to brokers fail to meet the criteria defined above the Turnilo instance is marked as unhealthy.
-# Response examples
+## Response examples
Healthy response example:
```
diff --git a/docs/index.md b/docs/index.md
index 45cf0ff09..51230c2c6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,39 +1,39 @@
-# Documentation
-
-## Configuration
-
-### [Cluster](configuration-cluster.md)
-
-How to configure Turnilo server and connect to Druid cluster.
-
-### [Datacubes](configuration-datacubes.md)
-
-How to configure dimensions and measures in data cubes.
-
-### [Customiztion](configuration-customizations.md)
-
-How to configure built-in customization in Turnilo (URL shortener, CSS, Sentry error reporting, etc).
-
-## [Generating Links](generating-links.md)
-
-How to integrate 3rd party tools with Turnilo.
-
-## [Health checking](health-checking.md)
-
-How to configure Turnilo to run in HA mode on the cluster behind load balancer.
-
-## [Release management](release-management.md)
-
-How to release Turnilo in semi-automatic way using Github actions.
-
-## [Custom Extensions](extending-turnilo.md)
-
-How to customize Turnilo, plugins, query and request decorators.
-
-## [OAuth integration](oauth.md)
-
-How to integrate Turnilo with OAuth provider.
-
-## [Web performance](webperf.md)
-
-How to take care of a web performance.
\ No newline at end of file
+---
+title: Turnilo
+nav_order: 1
+---
+
+Turnilo is a business intelligence, data exploration and visualization web application for [Apache Druid](https://druid.apache.org).
+Turnilo is a fork of [Pivot](https://github.com/implydata/pivot) which is currently available under commercial licence only.
+This repository was forked from the stalled repository [Swiv](https://github.com/yahoo/swiv)
+with the latest version of Pivot under Apache license.
+
+## Motivation
+
+[Druid](https://github.com/druid-io/druid) is heavily used as business intelligence platform at [Allegro](https://allegro.tech/).
+In order to gain wide adoption of non-technical users, Druid requires simple yet powerful user interface.
+In Allegro, we have decided that we are going to continue Pivot development as an open source software,
+this is how Turnilo emerged.
+
+## Manifesto
+
+* High usability for non-technical users over sophisticated but rarely used features.
+* Focus on interactive data exploration over static predefined dashboards.
+* Self-describing reports for users without deep domain expertise.
+* Outstanding integration with Druid over support for other data sources like SQL databases.
+* Focus on data visualizations over Druid cluster or data ingestion management.
+* Data cubes configuration as a code over UI editor backed by non-versioned database.
+* Stateless over stateful server-side architecture.
+* Support for most recent versions of standards compliant browsers.
+
+## Features
+
+* Intuitive, drag and drop, gorgeous user interface to visualize Druid datasets.
+* Fully dedicated to low latency Druid
+ [Timeseries](https://druid.apache.org/docs/latest/querying/timeseriesquery.html),
+ [TopN](https://druid.apache.org/docs/latest/querying/topnquery.html) and
+ [GroupBy](https://druid.apache.org/docs/latest/querying/groupbyquery.html) queries.
+* Unified view for historical and real-time data.
+* Blazingly fast.
+
+
diff --git a/docs/oauth.md b/docs/oauth.md
index e422d8e56..73f15d973 100644
--- a/docs/oauth.md
+++ b/docs/oauth.md
@@ -1,8 +1,9 @@
-# OAuth integration
-
-* TOC
- {:toc}
-
+---
+title: OAuth integration
+nav_order: 9
+layout: page
+---
+
## Overview
Turnilo can integrate with your OAuth provider.
@@ -34,4 +35,4 @@ oauth:
## Further reading
-Please refer to our [github discussion](https://github.com/allegro/turnilo/discussions/734) for our use case.
+Please refer to our [GitHub discussion](https://github.com/allegro/turnilo/discussions/734) for our use case.
diff --git a/docs/release-management.md b/docs/release-management.md
index 6a4b2a7e8..79a184838 100644
--- a/docs/release-management.md
+++ b/docs/release-management.md
@@ -1,7 +1,8 @@
-# Turnilo Release Management
-
-* TOC
-{:toc}
+---
+title: Release management
+nav_order: 7
+layout: page
+---
## Overview
@@ -10,12 +11,12 @@ Release management is automated by [Release It](https://github.com/release-it/re
* Build & Test
* Bump version in package.json
* Commit, push and tag Git repository
-* Create Github [release](https://github.com/allegro/turnilo/releases) with generated changelog
+* Create GitHub [release](https://github.com/allegro/turnilo/releases) with generated changelog
* Publish Turnilo package to the [npm](https://www.npmjs.com/package/turnilo) registry
## Final Release
-:point_up: Final release must be done on the master branch
+Final release must be done on the master branch
Use [Final Release](https://github.com/allegro/turnilo/actions/workflows/release-final.yml) action and select "Run Workflow"
diff --git a/docs/webperf.md b/docs/webperf.md
index b0551ae05..8f845d98e 100644
--- a/docs/webperf.md
+++ b/docs/webperf.md
@@ -1,7 +1,8 @@
-# Web performance
-
-* TOC
- {:toc}
+---
+title: Application performance
+nav_order: 10
+layout: page
+---
## Overview
@@ -18,7 +19,7 @@ Tools like [Bundlephobia](https://bundlephobia.com/) will help to recon cost of
### Size-limit
-[Size-limit Github Action](https://github.com/marketplace/actions/size-limit-action) will help to stay with assets size in the budget.
+[Size-limit GitHub Action](https://github.com/marketplace/actions/size-limit-action) will help to stay with assets size in the budget.
On each pull request this action will post a comment with current bundle size and its delta.
**Each time budgets are exceeded CI will fail.**
@@ -29,8 +30,8 @@ You can adjust budgets in `size-limit` section of `package.json`.
On every build a report about Webpack's bundle is made by [Statoscope](https://statoscope.tech/).
You can find these under `build/report-*.html`.
-Among others it offers detailed tree-map of the client bundle.
-For example it helps to figure out which dependencies are the heaviest.
+Among others, it offers detailed tree-map of the client bundle.
+For example, it helps to figure out which dependencies are the heaviest.
### Transpiling dependencies
@@ -40,10 +41,10 @@ Any dependency that has to be transpiled should be [listed within Webpack config
### Manual (dead) code elimination
-Sometimes we can't rely on libraries' authors or on Webpack in terms of tree-shaking aka dead-code-elimantion and we have to take matters into our own hands.
+Sometimes we can't rely on libraries' authors or on Webpack in terms of tree-shaking aka dead-code-elimination, and we have to take matters into our own hands.
Webpack by [`IgnorePlugin`](https://webpack.js.org/plugins/ignore-plugin/) allows to drop selected modules and this [how Moment's locales are not included in the final bundle](../config/webpack.common.js#45).
## Lighthouse
-On each pull request [Lighthouse-CI](https://github.com/GoogleChrome/lighthouse-ci) action will post link to lighthouse report. It can help to measure current performance and notice potential performance issues.
\ No newline at end of file
+On each pull request [Lighthouse-CI](https://github.com/GoogleChrome/lighthouse-ci) action will post link to lighthouse report. It can help to measure current performance and notice potential performance issues.