improved documentation layout and design

kamon-io · Mar 16, 2022 · 30d328f · 30d328f
1 parent 1e74e15
commit 30d328f
Show file tree

Hide file tree

Showing 32 changed files with 430 additions and 573 deletions.
diff --git a/_data/docs/latest.yaml b/_data/docs/latest.yaml
@@ -1,9 +1,9 @@
 documentation:
-  - name: Guides
+  - name: Installation
     path: /guides/
     icon: /assets/img/icons/docs-guides.svg
     topics:
-      - name: Installation
+      - name: With Kamon Telemetry
         path: /guides/installation/
         pages:
           - name: Akka HTTP
@@ -60,7 +60,7 @@ documentation:
     path: /instrumentation/
     icon: /assets/img/icons/docs-instrumentation.svg
     topics:
-      - name: Automatic
+      - name: Supported Frameworks
         path: /instrumentation/
         pages:
           - name: Akka

diff --git a/_includes/metric-detail.md b/_includes/metric-detail.md
@@ -3,24 +3,24 @@
 {% assign metric_info = site.data.docs[current_version].metrics[include.name] %}
 
 <div class="container-fluid">
-  <div class="row metric-detail elevated-container py-4 my-2" markdown="0" data-toggle="collapse" data-target="#{{ include.name | replace: ".", "_" }}" style="cursor: pointer;">
+  <div class="row metric-detail elevated-container py-3 px-2 my-2" markdown="0" data-toggle="collapse" data-target="#{{ include.name | replace: ".", "_" }}" style="cursor: pointer;">
     <div class="col-12 w-100">
-    <a>
-      <strong class="mr-2 w-100">{{ include.name}}</strong> 
-      <span class="text-tag-green" style="display: inherit;">{{ metric_info.instrument_type }}</span>
+    <a class="no-decoration">
+      <strong class="metric-name mr-2 w-100">{{ include.name}}</strong> 
+      <span style="display: inherit;">{{ metric_info.instrument_type }}</span>
+      <div class="metric-description">{{ metric_info.description }}</div>
     </a>
     </div>
-    <div id="{{ include.name | replace: ".", "_" }}" class="col-12 collapse">
-      <div class="mt-2">{{ metric_info.description }}</div>
+    <div id="{{ include.name | replace: ".", "_" }}" class="col-12 collapse metric-tags">
+      <div class=""></div>
       {% if metric_info.tags %}
         <br>
-        <p>Instruments are tagged with:
-          <ul>
-            {% for tag in metric_info.tags %}
-              <li><span class="font-weight-bold text-dark-2">{{ tag.name }}</span>: {{ tag.description }}</li>
-            {% endfor %}
-          </ul>
-        </p>
+        <div class="mb-1">Tags included by default:</div>
+        <ul class="pl-4">
+          {% for tag in metric_info.tags %}
+            <li><span class="metric-tag-name text-dark-2">{{ tag.name }}</span>: {{ tag.description }}</li>
+          {% endfor %}
+        </ul>
       {% endif %}
     </div>
   </div>

diff --git a/_layouts/docs.html b/_layouts/docs.html
@@ -1,6 +1,6 @@
 ---
 layout: default
-footer_background: bg-lightest
+footer_background: bg-white
 ---
 {% assign path_sections = page.url | split: '/' %}
 {% assign current_version = path_sections[2] %}
@@ -12,6 +12,9 @@
 {% assign latest_version_link = page.url | replace: current_version, "latest" %}
 {% assign path_without_version = path_sections | drop: 3 | join: "/" | prepend: "/" | append: "/" %}
 
+{% assign current_section = '' %}
+{% assign current_topic = '' %}
+
 
 <nav class="d-lg-none mobile-docs-navbar" role="button">
   <div class="d-flex align-items-center h-100" type="button" data-toggle="collapse" data-target="#mobile-docs-navigation" aria-controls="mobile-docs-navigation" aria-expanded="false" aria-label="Toggle navigation">
@@ -43,7 +46,7 @@ <h4 class="d-inline mb-0" type="button" data-toggle="collapse" data-target="#mob
 
         <ul id="{{ section_id }}" class="collapse {% if is_section_expanded %}show{% endif %}" aria-labelledby="{{ section_id }}">
           {% for topic in section.topics %}
-          <li class="pb-3">
+          <li class="mb-3">
             <div class="docs-topic py-2 ">{{ topic.name }}</div>
 
             <ul>
@@ -92,39 +95,42 @@ <h4 class="d-inline mb-0" type="button" data-toggle="collapse" data-target="#mob
   {% endif %}
 </nav>
 
-<div class="w-100"  style="background-color: #FAFAFC;">
+<div class="w-100">
   <div class="container-lg pb-5 pt-5">
     <div class="row">
 
       {% if documentation %}
       <div id="docs-sidebar" class="d-none d-lg-block col-3 p-0 pr-3 docs-sidebar-nav d-none d-lg-block sticky-docs-navbar">
-        <div class="doc-search-container">
-          <input id="docSearch" type="text" placeholder="Search the Docs...">
-          <img class="doc-search-icon" src="/assets/img/icons/search-icon.svg" />
+        <span class="h3">
+          Documentation
+        </span>
+        <div class="doc-search-container mt-3">
+          <input id="docSearch" type="text" placeholder="Find a topic...">
+          <img class="doc-search-icon" src="/assets/img/icons/search.svg" />
         </div>
-        <ul>
+        <ul style="scrollbar-gutter: auto;">
           {% for section in documentation %}
           {% assign section_id = section.name | slugify %}
           {% assign is_section_expanded = path_without_version | start_with: section.path %}
 
           <li>
-            <div class="docs-section py-2 px-3 {% if is_section_expanded %}active{% else %}collapsed{% endif %}"
+            <div class="docs-section p-1 my-2 {% if is_section_expanded %}active{% else %}collapsed{% endif %}"
               type="button"
               data-toggle="collapse"
               data-target="#{{ section_id }}"
               aria-expanded="{{ is_section_expanded }}"
               aria-controls="{{ section_id }}">
 
-              <span style="padding-left: 2rem; background-image: url({{section.icon}}); background-repeat: no-repeat; background-size: contain;">{{ section.name }}</span>
               <span class="collapse-caret"></span>
+              <span class="ml-3">{{ section.name }}</span>
             </div>
 
-            <ul id="{{ section_id }}" class="collapse {% if is_section_expanded %}show{% endif %}" aria-labelledby="{{ section_id }}">
+            <ul id="{{ section_id }}" class="docs-section-contents my-2 collapse {% if is_section_expanded %}show{% endif %}" aria-labelledby="{{ section_id }}">
               {% for topic in section.topics %}
-              <li class="pb-3">
-                <div class="docs-topic py-2 ">{{ topic.name }}</div>
+              <li class="mb-3">
+                <div class="docs-topic pb-2 ">{{ topic.name }}</div>
 
-                <ul>
+                <ul class="mb-4">
                   {% for page in topic.pages %}
                     <li>
                       {% if page.pages %}
@@ -136,25 +142,32 @@ <h4 class="d-inline mb-0" type="button" data-toggle="collapse" data-target="#mob
                         data-target="#{{ page_id }}"
                         aria-expanded="{{ is_page_expanded }}">
                         {{page.name}}
-                        <span class="collapse-caret collapse-caret-small"></span>
                       </div>
 
                       <ul id="{{ page_id }}" class="docs-sub-page-group collapse {% if is_page_expanded %}show{% endif %}">
-                        <div class="my-2">
+                        <div class="mb-2">
                           {% for sub_page in page.pages %}
                           <a href="/{{ version_prefix | append: sub_page.path }}">
-                            <li class="docs-sub-page py-2 {% if sub_page.path == path_without_version %}active{% endif %}">
+                            <li class="docs-sub-page py-1 {% if sub_page.path == path_without_version %}active{% endif %}">
                               {{sub_page.name}}
                             </li>
                           </a>
+                          {% if sub_page.path == path_without_version %}
+                            {% assign current_section = section.name %}
+                            {% assign current_topic = topic.name %}
+                          {% endif %}
                           {% endfor %}
                         </div>
                       </ul>
 
                       {% else %}
                       <a href="/{{ version_prefix | append: page.path }}">
-                        <div class="docs-page py-2 {% if page.path == path_without_version %}active{% endif %}">{{page.name}}</div>
+                        <div class="docs-page py-1 {% if page.path == path_without_version %}active{% endif %}">{{page.name}}</div>
                       </a>
+                        {% if page.path == path_without_version %}
+                          {% assign current_section = section.name %}
+                          {% assign current_topic = topic.name %}
+                        {% endif %}
                       {% endif %}
 
                     </li>
@@ -169,12 +182,26 @@ <h4 class="d-inline mb-0" type="button" data-toggle="collapse" data-target="#mob
       </div>
       {% endif %}
 
-      <div id="docs-content" class="docs-container px-5 pb-5 {% if documentation %}col-12 col-lg-9 {% else %}col-12{% endif %}">
+      <div id="docs-content" class="docs-container px-4 {% if documentation %}col-12 col-lg-9 col-xl-7 {% else %}col-12{% endif %}">
         {% if current_version == 'v1' %}
           {% include outdated-docs-notice.html link=latest_version_link %}
         {% endif %}
+
+        {% if current_section != '' %}
+        <div class="docs-breadcrumbs mb-3">
+          <span class="docs-breadcrumbs-section mr-3">{{current_section}}</span>/<span class="ml-3 docs-breadcrumns-topic">{{current_topic}}</span>
+        </div>
+        {% endif %}
+
         {% include anchor_headings.html html=content anchorBody="#" anchorClass="heading-anchor" %}
       </div>
+
+      <div id="docs-toc" class="docs-toc d-none d-xl-block col-0 col-lg-2 pt-1 pl-3">
+        <span class="toc-heading">On this article</span>
+        <div id="docs-toc-container">
+
+        </div>
+      </div>
     </div>
   </div>
 </div>

diff --git a/_plugins/alert.rb b/_plugins/alert.rb
@@ -10,11 +10,11 @@ def initialize(tag_name, text, tokens)
     def render(context)
       content = super
       <<-HTML.gsub /^\s+/, '' # remove whitespaces from here
-      <div class="outline-alert outline-alert-#{@type} row no-gutters">
-        <div class="alert-image col-2 col-sm-1">
-          <img src="/assets/img/icons/alert/#{@type}.svg"/>
+      <div class="outline-alert-#{@type} row no-gutters mt-3">
+        <div class="alert-image col-auto pl-0 pr-3">
+          <img height="32" width="32" src="/assets/img/icons/alert/#{@type}.svg"/>
         </div>
-        <div class="alert-content col-10 col-sm-11">#{content}</div>
+        <div class="alert-content col">#{content}</div>
       </div>
       HTML
     end

diff --git a/_plugins/code_block.rb b/_plugins/code_block.rb
@@ -6,11 +6,12 @@ def initialize(tag_name, text, tokens)
 
       parts = text.split(' ')
       @language = parts[0].nil? ? "text" : parts[0]
+      @file_name = parts[1].nil? ? "text" : parts[1]
     end
 
     def render(context)
       block_content = super.to_s.strip
-      '<div class="code-example-container"><pre class="code-example line-numbers language-'+ @language +'"><code class="language-'+ @language +'">'+ block_content +'</code></pre><div class="tab-footer"><div class="fa fa-copy"/></div></div>'
+      '<div class="code-example-container"><pre class="code-example language-'+ @language +'"><code class="language-'+ @language +'">'+ block_content +'</code></pre><div class="tab-footer"></div></div>'
 
     end
   end

diff --git a/_plugins/code_example.rb b/_plugins/code_example.rb
@@ -39,14 +39,14 @@ def render(context)
 
         tab_header = tab_header +
           '<li class="nav-item">' +
-            '<a class="nav-link btn btn-secondary btn-sm language-btn' + active + '" data-toggle="tab" data-target="#' + snippet_id + '" role="tab">' +
+            '<a class="nav-link btn btn-secondary btn-sm language-btn no-decoration' + active + '" data-toggle="tab" data-target="#' + snippet_id + '" role="tab">' +
               snippet[:label] +
             '</a>' +
           '</li>'
 
         tab_contents = tab_contents +
           '<div class="tab-pane' + active + '" id="' + snippet_id + '" role="tabpanel">' +
-            '<pre class="line-numbers language-'+ snippet[:language] +'">' +
+            '<pre class="language-'+ snippet[:language] +'">' +
               '<code class="language-'+ snippet[:language] +'">' +
                 code +
               '</code>' +
@@ -57,7 +57,7 @@ def render(context)
       tab_header = tab_header + '</ul></div>'
       tab_contents = tab_contents + '</div>'
 
-      tab_footer = '<div class="tab-footer"><div class="fa fa-copy"/></div>'
+      tab_footer = '<div class="tab-footer"><div class=""/></div>'
 
       '<div class="code-example code-example-container">' + tab_header + tab_contents + tab_footer + '</div>'
     end

diff --git a/_plugins/lightbox.rb b/_plugins/lightbox.rb
@@ -11,7 +11,7 @@ def render(context)
       content = super.strip
       <<-HTML.gsub /^\s+/, '' # remove whitespaces from here
       <div class="w-100 my-4 text-center kamon-lightbox">
-        <a href="#{@src}" data-caption="#{content}" data-fancybox="lightbox">
+        <a class="no-decoration" href="#{@src}" data-caption="#{content}" data-fancybox="lightbox">
           <img class="img-fluid mb-2" src="#{@src}" alt="#{content}">
           <br>
           #{content}

diff --git a/_sass/_bootstrap_overrides.scss b/_sass/_bootstrap_overrides.scss
@@ -10,6 +10,23 @@ $theme-colors: (
   "dark-background": $color-dark-background
 );
 
+$grid-breakpoints: (
+  xs: 0,
+  sm: 576px,
+  md: 768px,
+  lg: 992px,
+  xl: 1200px,
+  xxl: 1400px
+);
+
+$container-max-widths: (
+  sm: 540px,
+  md: 720px,
+  lg: 960px,
+  xl: 1140px,
+  xxl: 1368px
+);
+
 $btn-font-weight: $typography-weight-semi-bold;
 $btn-border-radius: remSize(8);
 $btn-border-radius-lg: remSize(12);
@@ -39,6 +56,13 @@ $display2-weight: 700;
 $display3-weight: 700;
 $display4-weight: 700;
 
+
+
+$h1-font-size: 2rem;
+$h2-font-size: 1.75rem;
+$h3-font-size: 1.5rem;
+$headings-font-weight: 600;
+
 $lead-font-weight: 400;
 $close-color: white;
 $close-text-shadow: none;