Merge pull request #181 from canonical/new-docs-layout

Update examples and docs for new layout
canonical · Nov 29, 2023 · 8a4c251 · 8a4c251
2 parents bed20c7 + d76048d
commit 8a4c251
Show file tree

Hide file tree

Showing 6 changed files with 561 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ Flask extension to integrate discourse content generated to docs to your website
 
 Documentation for how to write documentation pages in Discourse for consumption by this module and how to configure the website to use the module can be found [in the Canonical discourse](https://discourse.canonical.com/t/creating-discourse-based-documentation-pages/159).
 
-Example Flask template for documentation pages can be found in [`examples/document.html`](https://github.com/canonical-web-and-design/canonicalwebteam.discourse/blob/main/examples/document.html)
+Example Flask template for documentation pages can be found in [`examples`](/examples/) folder. Please refer to the [README](/examples/README.md) in that folder for more information.
 
 ## Install
 

diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,45 @@
+# Documentation layout for Discourse docs
+
+## Full-width documentation layout
+
+Vanilla 4.5.0 introduced a new full-width documentation layout. This layout is recommended for all new documentation sites.
+
+### Requirements
+
+To use new documentation layout you need to use Vanilla 4.5.0 or newer and Discourse 2.7.0 or newer (to have a support for automatically generated table of contents).
+
+### Layout
+
+Please familarise yourself with [the Vanilla documentation about the documentation layout](https://vanillaframework.io/docs/layouts/documentation) to have a better understanding of the structure.
+
+### Template for Discourse docs
+
+Example template for documentation pages can be found in [`examples/document.html`](document.html).
+
+This template needs to extend a base layout template of the project and replace the whole contents of the `<body>` element, because top navigation and footer need to be adjusted to new layout as well.
+
+It's recommended to have partial templates for header and footer and include them in the brochure layout template and in the documentation template. In our example the `is_docs`` template variable is used to differentiate between docs and other pages in partials so that they can render differently.
+
+#### Customisation
+
+There are several elements that can or need to be customised when applying the template to your project.
+
+- name of the base layout template that is being extended
+- contents of `{% block title %}` need to be adjusted
+- names and contents of partial templates for header and footer
+- adjust `expandable` parameter to `create_navigation` if expandable navigation is needed
+
+There may be other changes needed based on the project-specific needs.
+
+#### Example usage
+
+The new documentation layout is already used on [microk8s.io](https://microk8s.io/docs). You can refer to the pull request [canonical/mikrok8s.io#624](https://github.com/canonical/microk8s.io/pull/624/files) that introduced the new layout for an example of how to use it.
+
+## Old brochure site documentation layout
+
+For an example template of the old brochure site documentation layout, see [`examples/document-brochure.html`](document-brochure.html).
+
+Please note that the use of this old template is not recommended on new sites. Please use the official full-width documentation layout described above if possible.
+
+
+
diff --git a/examples/_footer.html b/examples/_footer.html
@@ -0,0 +1,63 @@
+{#
+    This is an example of footer partial to be used with documentation layout.
+    It extracts consists of 2 versions so they can be reused in standard brochure site layout
+    and documentation layout (based on the value of `is_docs` template variable).
+
+    See examples/README.md for more details.
+#}
+
+{% if is_docs %}
+<footer class="p-footer">
+  <div class="l-docs__subgrid">
+    <div class="l-docs__sidebar">
+      <div class="u-fixed-width">
+        <p>© {{ now("%Y") }} Canonical Ltd.</p>
+      </div>
+    </div>
+    <div class="l-docs__main">
+      <div class="row">
+        <div class="col-3 col-medium-2">
+          <ul class="p-list is-dark">
+            <li class="p-list__item--condensed">
+              <a href="https://www.ubuntu.com/legal">Legal information</a>
+            </li>
+            <li class="p-list__item--condensed">
+              <a href="" class="js-revoke-cookie-manager">Manage your tracker settings</a>
+            </li>
+            <li class="p-list__item--condensed">
+              <a class="p-footer__link" href="https://github.com/canonical/[YOUR REPO HERE]/issues/new">Report a bug on this site</a>
+            </li>
+          </ul>
+        </div>
+        <div class="col-9 col-medium-4">
+          <p>Ubuntu and Canonical are registered trademarks of Canonical&nbsp;Ltd.</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</footer>
+{% else %}
+<footer class="p-footer l-footer--sticky">
+  <div class="row">
+    <div class="col-3 col-medium-2">
+      <p>© {{ now("%Y") }} Canonical Ltd.</p>
+    </div>
+    <div class="col-3 col-medium-2">
+      <ul class="p-list is-dark">
+        <li class="p-list__item--condensed">
+          <a href="https://www.ubuntu.com/legal">Legal information</a>
+        </li>
+        <li class="p-list__item--condensed">
+          <a href="" class="js-revoke-cookie-manager">Manage your tracker settings</a>
+        </li>
+        <li class="p-list__item--condensed">
+          <a class="p-footer__link" href="https://github.com/canonical/[YOUR REPO HERE]/issues/new">Report a bug on this site</a>
+        </li>
+      </ul>
+    </div>
+    <div class="col-6 col-medium-2">
+      <p>Ubuntu and Canonical are registered trademarks of Canonical&nbsp;Ltd.</p>
+    </div>
+  </div>
+</footer>
+{% endif %}
diff --git a/examples/_header.html b/examples/_header.html
@@ -0,0 +1,59 @@
+{#
+    This is an example of top navigation header partial to be used with documentation layout.
+    It extracts common navigation elements (logo and navigation items) into macros,
+    so they can be reused in standard brochure site layout and documentation layout
+    (based on the value of `is_docs` template variable).
+
+    See examples/README.md for more details.
+#}
+
+{% macro nav_logo() %}
+<div class="p-navigation__banner {% if not is_docs %}u-no-padding--left{% endif %}">
+  <div class="p-navigation__tagged-logo">
+    <a class="p-navigation__link" href="/">
+      <div class="p-navigation__logo-tag">
+        <img class="p-navigation__logo-icon" src="https://assets.ubuntu.com/v1/82818827-CoF_white.svg" alt="Canonical" width="95">
+      </div>
+      <span class="p-navigation__logo-title">Canonical</span>
+    </a>
+  </div>
+  <a href="#navigation" class="p-navigation__toggle--open" title="menu">Menu</a>
+  <a href="#navigation-closed" class="p-navigation__toggle--close" title="close menu">Close menu</a>
+</div>
+{% endmacro %}
+
+{% macro nav_items() %}
+<nav class="p-navigation__nav" aria-label="main-navigation">
+  <ul class="p-navigation__items">
+    <li class="p-navigation__item {% if request.path in ['/docs',] %}is-selected{% endif %}">
+      <a href="/docs" class="p-navigation__link">Docs</a>
+    </li>
+    {#
+        FIXME: Put your navigation items here
+    #}
+  </ul>
+  <ul class="p-navigation__items global-nav"></ul>
+</nav>
+{% endmacro %}
+
+<a href="#main-content" class="p-link--skip">Jump to main content</a>
+
+<header id="navigation" class="p-navigation is-dark">
+  {% if is_docs %}
+  <div class="l-docs__subgrid">
+    <div class="l-docs__sidebar">
+      {{ nav_logo() }}
+    </div>
+    <div class="l-docs__main">
+      <div class="p-navigation__row u-fixed-width">
+        {{ nav_items() }}
+      </div>
+    </div>
+  </div>
+  {% else %}
+  <div class="p-navigation__row">
+      {{ nav_logo() }}
+      {{ nav_items() }}
+  </div>
+  {% endif %}
+</header>