Skip to content

Commit

Permalink
Merge pull request #290 from canonical/implement-documentation-layout
Browse files Browse the repository at this point in the history 
Implement new documentation layout
  • Loading branch information
@petesfrench
petesfrench authored Jan 25, 2024
2 parents 7b31733 + 3d4024c commit 8170248
Show file tree
Hide file tree
Showing 9 changed files with 234 additions and 123 deletions.
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
"postcss": "8.4.20",
"postcss-cli": "10.1.0",
"sass": "1.57.1",
"vanilla-framework": "3.15.1",
"vanilla-framework": "4.5.1",
"webpack-cli": "4.10.0"
},
"devDependencies": {
Expand Down
1 change: 1 addition & 0 deletions static/sass/_settings.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ $breakpoint-navigation-threshold: 940px;
// Sidebar
$content-padding: 0 5%;
$sidebar-width: 18rem;
$l-documentation-sidebar-width: 18rem;
8 changes: 8 additions & 0 deletions static/sass/styles.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,11 @@
margin-bottom: 0 !important;
}
}

// TODO: to be removed when fixed in Vanilla
// https://github.com/canonical/vanilla-framework/issues/4947
body:not(.docs) {
.p-navigation__banner {
padding-left: 0;
}
}
4 changes: 3 additions & 1 deletion templates/base_layout.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,18 +58,20 @@
<link rel="stylesheet" type="text/css" media="screen" href="{{ versioned_static('css/styles.css') }}" />
</head>

<body>
<body class="{% block page_class %}{% endblock %}">
<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-MV7Z9M3" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->

{% block body%}
{% include "partial/_navigation.html" %}

<div id="main-content">
{% block content %}{% endblock content %}
</div>

{% include "partial/_footer.html" %}
{% endblock body %}
<script src="{{ versioned_static('js/build/global-nav/global-nav.js') }}"></script>
<script src="{{ versioned_static('js/build/cookie-policy/cookie-policy.js') }}"></script>
<script>
Expand Down
91 changes: 67 additions & 24 deletions templates/docs/document.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
{% block page_class %}docs{% endblock %}
{% block content_class %}l-docs-wrapper{% endblock %}
{% block page_title %}| {{ document.title }} {% endblock %}
{% set is_docs = True %}

{% block content %}
{% block body %}
{% macro create_navigation(nav_items) %}
<ul>
{% for element in nav_items %}
Expand All @@ -25,20 +26,25 @@
</ul>
{% endmacro %}

<section id="search-docs" class="p-strip--light is-shallow">
<div class="row">
<form class="p-search-box u-no-margin--bottom" action="/docs/search">
<input type="search" class="p-search-box__input" name="q" {% if query %}value="{{ query }}"{% endif %} placeholder="Search documentation" required/>
<button type="button" class="p-search-box__reset" alt="reset" onclick="this.previousElementSibling.value = '';this.previousElementSibling.focus()"><i class="p-icon--close">Reset</i></button>
<button type="submit" class="p-search-box__button" alt="search"><i class="p-icon--search">Search</i></button>
</form>
<div class="l-docs">
<div class="l-docs__header">
{% include "partial/_navigation.html" %}
<section id="search-docs" class="p-strip--light is-shallow l-docs__subgrid">
<div class="l-docs__main">
<div class="row">
<form class="p-search-box u-no-margin--bottom" action="/docs/search">
<input type="search" class="p-search-box__input" name="q" {% if query %}value="{{ query }}"{% endif %} placeholder="Search documentation" required/>
<button type="button" class="p-search-box__reset" alt="reset" onclick="this.previousElementSibling.value = '';this.previousElementSibling.focus()"><i class="p-icon--close">Reset</i></button>
<button type="submit" class="p-search-box__button" alt="search"><i class="p-icon--search">Search</i></button>
</form>
</div>
</div>
</section>
</div>
</section>

<div class="p-strip is-shallow">
<div class="row">
<aside class="col-3">
<div class="p-side-navigation--raw-html" id="drawer">
<div class="l-docs__sidebar">
<div class="l-docs__sticky-container">
<nav class="p-side-navigation--raw-html" id="drawer" style="margin-top:0.5rem;">
<a href="#drawer" class="p-side-navigation__toggle js-drawer-toggle" aria-controls="drawer">
Toggle side navigation
</a>
Expand All @@ -64,21 +70,58 @@ <h3>{{ nav_group.navlink_text }}</h3>
{{ create_navigation(nav_group.children) }}
{% endfor %}
</div>
</nav>
</div>
</div>

<div class="l-docs__title">
<div class="u-fixed-width">
{% if document.title %}
<div class="p-section--shallow u-no-padding--top">
<h1 class="u-no-margin--bottom">{{ document.title }}</h1>
</div>
</aside>
{% endif %}
</div>
</div>

{% if document.headings_map is defined and document.headings_map|length > 0 %}
<div class="l-docs__meta">
<div class="l-docs__sticky-container">
<aside class="p-table-of-contents">
<div class="p-table-of-contents__section">
<h4 class="p-table-of-contents__header">On this page</h4>
<nav class="p-table-of-contents__nav" aria-label="Table of contents">
<ul class="p-table-of-contents__list">
{% for heading in document.headings_map %}
<li class="p-table-of-contents__item"><a class="p-table-of-contents__link" href="#{{ heading.heading_slug }}">{{ heading.heading_text }}</a></li>
{% endfor %}
</ul>
</nav>
</div>
</aside>
</div>
</div>
{% endif %}

<main class="col-9">
<h1>{{ document.title }}</h1>
<div class="l-docs__main u-text-max-width">
<main class="u-fixed-width">
<div class="p-strip is-shallow" style="overflow: visible;">
{{ document.body_html | safe }}
<div class="p-strip is-shallow">
<div class="p-notification--information">
<p class="p-notification__content">
Last updated {{ document.updated }}. <a href="{{ forum_url }}{{ document.topic_path }}">Help improve this document in the forum</a>.
</p>
</div>
</div>
</div>

<div class="p-strip is-shallow">
<div class="p-notification--information">
<div class="p-notification__content">
<p class="p-notification__message">Last updated {{ document.updated }}. <a href="{{ forum_url }}{{ document.topic_path }}">Help improve this document in the forum</a>.</p>
</div>
</div>
</div>
</main>
</div>

<div class="l-docs__footer">
{% include "partial/_footer.html" %}
</div>
</div>

<script>
Expand Down Expand Up @@ -149,4 +192,4 @@ <h1>{{ document.title }}</h1>

setupSideNavigations('.p-side-navigation, [class*="p-side-navigation--"]');
</script>
{% endblock %}
{% endblock body %}
116 changes: 57 additions & 59 deletions templates/docs/search.html
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{% extends "base_layout.html" %}

{% block meta %}
{{ super() }}
<meta name="robots" content="noindex" />
{{ super() }}
<meta name="robots" content="noindex" />
{% endblock %}

{% block page_class %}docs{% endblock %}
Expand All @@ -20,73 +20,71 @@
</div>
</section>

<div class="l-docs">
<div class="p-strip is-shallow u-no-padding--bottom">
<div class="row">
<div class="col-12">
{% if results and results.entries %}
<h1 class="p-heading--2 u-no-margin--bottom">We've found these results for your search <strong>"{{ query }}"</strong></h1>
{% else %}
<h1 class="p-heading--2 u-no-margin--bottom">We haven't found any results for your search <strong>"{{ query }}"</strong>.</h1>
{% endif %}
</div>
<div class="p-strip is-shallow u-no-padding--bottom">
<div class="row">
<div class="col-12">
{% if results and results.entries %}
<h1 class="p-heading--2 u-no-margin--bottom">We've found these results for your search <strong>"{{ query }}"</strong></h1>
{% else %}
<h1 class="p-heading--2 u-no-margin--bottom">We haven't found any results for your search <strong>"{{ query }}"</strong>.</h1>
{% endif %}
</div>
</div>
</div>

{% if results and results.entries %}
{% for item in results.entries %}
<div class="p-strip is-bordered is-shallow">
<div class="row">
<div class="col-12">
<h5><a href="{{ item.link }}" class="title-main">{{ item.htmlTitle | safe}}</a></h5>
<p>
{{ item.htmlSnippet | safe }}
</p>
<small><a href="{{ item.link }}">{{ item.htmlFormattedUrl | safe }}</a></small>
</div>
{% if results and results.entries %}
{% for item in results.entries %}
<div class="p-strip is-bordered is-shallow">
<div class="row">
<div class="col-12">
<h5><a href="{{ item.link }}" class="title-main">{{ item.htmlTitle | safe}}</a></h5>
<p>
{{ item.htmlSnippet | safe }}
</p>
<small><a href="{{ item.link }}">{{ item.htmlFormattedUrl | safe }}</a></small>
</div>
</div>
{% endfor %}
<div class="p-strip p-article-pagination">
{% if results.queries and results.queries.previousPage %}
<a
class="p-article-pagination__link--previous"
href="/docs/search?q={{ query }}&amp;start={{ results.queries.previousPage.0.startIndex }}{% if siteSearch %}&amp;siteSearch={{ siteSearch }}{% endif %}"
>
<span class="p-article-pagination__label">Previous</span>
</a>
{% endif %}
{% if results.queries and results.queries.nextPage %}
</div>
{% endfor %}
<div class="p-strip p-article-pagination">
{% if results.queries and results.queries.previousPage %}
<a
class="p-article-pagination__link--next"
href="/docs/search?q={{ query }}&amp;start={{ results.queries.nextPage.0.startIndex }}{% if siteSearch %}&amp;siteSearch={{ siteSearch }}{% endif %}"
class="p-article-pagination__link--previous"
href="/docs/search?q={{ query }}&amp;start={{ results.queries.previousPage.0.startIndex }}{% if siteSearch %}&amp;siteSearch={{ siteSearch }}{% endif %}"
>
<span class="p-article-pagination__label">Next</span>
<span class="p-article-pagination__label">Previous</span>
</a>
{% endif %}
</div>
{% else %}
<div class="p-strip">
<div class="row">
<div class="col-6">
<h3>Why not try widening your search?</h3>
<p>You can do this by:</p>
<ul class="p-list">
<li class="p-list__item is-ticked">Adding alternative words or phrases</li>
<li class="p-list__item is-ticked">Using individual words instead of phrases</li>
<li class="p-list__item is-ticked">Trying a different spelling</li>
</ul>
</div>
<div class="col-6">
<h3>Still no luck?</h3>
<ul class="p-list">
<li class="p-list__item is-ticked"><a href="/docs">Visit dqlite.io/docs</a></li>
<li class="p-list__item is-ticked"><a href="https://discourse.dqlite.io/">Ask on the forum</a></li>
</ul>
</div>
{% endif %}
{% if results.queries and results.queries.nextPage %}
<a
class="p-article-pagination__link--next"
href="/docs/search?q={{ query }}&amp;start={{ results.queries.nextPage.0.startIndex }}{% if siteSearch %}&amp;siteSearch={{ siteSearch }}{% endif %}"
>
<span class="p-article-pagination__label">Next</span>
</a>
{% endif %}
</div>
{% else %}
<div class="p-strip">
<div class="row">
<div class="col-6">
<h3>Why not try widening your search?</h3>
<p>You can do this by:</p>
<ul class="p-list">
<li class="p-list__item is-ticked">Adding alternative words or phrases</li>
<li class="p-list__item is-ticked">Using individual words instead of phrases</li>
<li class="p-list__item is-ticked">Trying a different spelling</li>
</ul>
</div>
<div class="col-6">
<h3>Still no luck?</h3>
<ul class="p-list">
<li class="p-list__item is-ticked"><a href="/docs">Visit dqlite.io/docs</a></li>
<li class="p-list__item is-ticked"><a href="https://discourse.dqlite.io/">Ask on the forum</a></li>
</ul>
</div>
</div>
{% endif %}
</div>
{% endif %}
{% endblock content %}

40 changes: 37 additions & 3 deletions templates/partial/_footer.html
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,43 @@
{% if is_docs %}
<footer class="p-footer p-strip--light">
<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">
<li class="p-list__item">
<a aria-label="External link to the Ubuntu legal information page" href="http://www.ubuntu.com/legal">
Legal information
</a>
</li>
<li class="p-list__item">
<a aria-label="External link to report a bug on Github" href="https://github.com/canonical-web-and-design/dqlite.io/issues/new">
Report a bug on this site
</a>
</li>
<li class="p-list__item">
<a href="" class="js-revoke-cookie-manager">Manage your tracker settings</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-strip--light">
<div class="row">
<div class="col-12">
<p>&copy; {{ now("%Y") }} Canonical Ltd.</p>
<p>Ubuntu and Canonical are registered trademarks of Canonical&nbsp;Ltd.</p>
<nav>
<ul class="p-inline-list--middot">
<li class="p-inline-list__item">
Expand All @@ -18,10 +54,8 @@
<a href="" class="js-revoke-cookie-manager">Manage your tracker settings</a>
</li>
</ul>
<span class="u-off-screen">
<a href="#">Go to the top of the page</a>
</span>
</nav>
</div>
</div>
</footer>
{% endif%}
Loading

0 comments on commit 8170248

Please sign in to comment.