Skip to content

Commit

Permalink
Upgrade Discourse docs to v5, use revised index topic (#772)
Browse files Browse the repository at this point in the history 
* feat: port to discourse docs v5, extract init_docs, init_tutorials

---------

Co-authored-by: Francisco Jimenez Cabrera <[email protected]>
Co-authored-by: Peter Makowski <[email protected]>
  • Loading branch information
@sparkiegeek @jkfran @petermakowski
3 people authored Apr 21, 2023
1 parent a0b9436 commit 4462606
Show file tree
Hide file tree
Showing 11 changed files with 419 additions and 804 deletions.
10 changes: 10 additions & 0 deletions konf/site.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,16 @@ env:
key: google-custom-search-key
name: google-api

- name: DISCOURSE_API_KEY
secretKeyRef:
key: maas-api-key
name: discourse-api

- name: DISCOURSE_API_USERNAME
secretKeyRef:
key: maas-api-username
name: discourse-api

extraHosts:
- domain: docs.maas.io
- domain: maas.ubuntu.com
Expand Down
2 changes: 1 addition & 1 deletion requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
canonicalwebteam.flask_base==1.1.0
canonicalwebteam.blog==6.4.0
canonicalwebteam.discourse-docs==1.0.1
canonicalwebteam.discourse==5.4.1
canonicalwebteam.http==1.0.3
canonicalwebteam.templatefinder==1.0.0
canonicalwebteam.search==1.3.0
Expand Down
282 changes: 250 additions & 32 deletions templates/docs/document.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,40 @@
{% block og_title %}{{ document.title }}{% endblock %}
{% block og_description %}{% endblock %}

{% macro create_navigation(nav_items, expandable=False, expanded=False) %}
<ul class="p-side-navigation__list">
{% for element in nav_items %}
<li class="p-side-navigation__item">
{% if element.navlink_href %}
<a
class="p-side-navigation__link {% if expandable and element.children %}is-expandable{% endif %}"
href="{{ element.navlink_href }}"
{% if expandable and element.children %}aria-expanded={% if expanded or element.is_active %}"true"{% else %}"false"{% endif %}{% endif %}
{% if element.is_active and not element.navlink_fragment %}aria-current="page"{% endif %}
>{{ element.navlink_text }}</a>
{% else %}
<strong
class="p-side-navigation__text {% if expandable and element.children %}is-expandable{% endif %}"
{% if expandable and element.children %}aria-expanded={% if expanded %}"true"{% else %}"false"{% endif %}{% endif %}
{% if element.is_active %}aria-current="page"{% endif %}
>{{ element.navlink_text }}</strong>
{% endif %}

{% if expandable %}
{% if element.children %}
<button class="p-side-navigation__expand" aria-expanded={% if element.is_active or element.has_active_child %}"true"{% else %}"false"{% endif %} aria-label="show submenu for {{ element.navlink_text }}"></button>
{% endif %}
{{ create_navigation(element.children, expandable, element.is_active or element.has_active_child) }}
{% else %}
{% if element.children %}
{{ create_navigation(element.children, expandable) }}
{% endif %}
{% endif %}
</li>
{% endfor %}
</ul>
{% endmacro %}

{% block content %}
<section id="search-docs" class="p-strip--light is-shallow">
<div class="row">
Expand All @@ -18,68 +52,252 @@
</form>
</div>
</section>

<div class="l-docs">
<aside class="l-docs-sidebar" id="navigation">
<i class="p-sidenav__toggle p-icon--menu u-hide u-show--small"></i>
<nav class="p-sidenav__body u-hide--small">
{{ navigation | safe }}
</nav>
<aside class="col-3 l-docs-sidebar">
{% if versions | length > 1 %}
<label for="version-select" class="u-hide">Version</label>
<select name="version-select" id="version-select" onChange="window.location.href=this.value">
{% for version in versions %}
{% set active = docs_version == version['path'] %}
<option value="{{ version_paths[version['path']] }}"{% if active %} selected{% endif %}>{{ version['version'] }}</option>
{% endfor %}
<select>
{% endif %}

<div class="row">
<div class="p-strip is-shallow">
<nav data-js="navigation" class="p-side-navigation" id="{{ navigation['path'] or 'default' }}">
<a href="#{{ navigation['path'] or 'default' }}" class="p-side-navigation__toggle js-drawer-toggle" aria-controls="{{ navigation['path'] or 'default' }}">
Toggle side navigation
</a>
<div class="p-side-navigation__overlay js-drawer-toggle" aria-controls="{{ navigation['path'] or 'default' }}"></div>
<div class="p-side-navigation__drawer">
<div class="p-side-navigation__drawer-header">
<a href="#" class="p-side-navigation__toggle--in-drawer js-drawer-toggle" aria-controls="{{ navigation['path'] or 'default' }}">
Toggle side navigation
</a>
</div>
{% for nav_group in navigation.nav_items %}
{% if not nav_group.hidden %}
{% if nav_group.navlink_text %}
{% if nav_group.navlink_href %}
<h3 class="p-side-navigation__heading--linked">
<a class="p-side-navigation__link" href="{{ nav_group.navlink_href }}" {% if nav_group.is_active %}aria-current="page"{% endif %}>
{{ nav_group.navlink_text }}
</a>
</h3>
{% else %}
<h3 class="p-side-navigation__heading">{{ nav_group.navlink_text }}</h3>
{% endif %}
{% endif %}
{#
Use `create_navigation(nav_group.children)` for a default, fully expanded navigation.
Use `create_navigation(nav_group.children, expandable=True)` for the nested nav levels to expand only when parent page is active.
#}
{{ create_navigation(nav_group.children, expandable=True) }}
{% endif %}
{% endfor %}
</div>
</nav>
</div>
</div>
</aside>
<main class="l-docs-content" id="main-content">
<main class="col-9 l-docs-content" id="content-section">
<div class="p-strip--light is-shallow l-docs-title">
<div class="l-docs-row row">
<h1 class="u-no-margin--bottom l-docs-title__heading">{{ document.title }}</h1>
<h1 class="l-docs-title__heading u-no-margin--bottom">{{ document.title }}</h1>
</div>
</div>

<div class="p-strip is-shallow">
<div class="l-docs-row row">
{{ document.body_html | safe }}
</div>
</div>

<div class="p-strip is-shallow u-no-padding--bottom">
<div class="l-docs-row row">
<hr />
<i>Last updated {{ document.updated }}.</i>
<p><i>Last updated {{ document.updated }}.</i></p>
</div>
</div>
<div class="p-strip is-shallow u-no-padding--bottom u-sticky--bottom">
<div class="l-docs-row row">
<div class="p-notification--information">
<p class="p-notification__content">
<a href="{{ forum_url }}{{ document.topic_path }}">Help improve this document in the forum</a>.
</p>
<div class="p-notification__content">
<p class="p-notification__message">
<a href="{{ forum_url }}{{ document.topic_path }}">Help improve this document in the forum</a>.
</p>
</div>
</div>
</div>
</div>
</main>
</div>
{% endblock %}
{% block js_extra %}
<script src="/static/js/highlight.pack.js"></script>
<script>
// Set up highlightjs
hljs.initHighlightingOnLoad();

document.addEventListener("DOMContentLoaded", function(event) {
// Toggle mobile sidebar nav
var toggle = document.querySelector('.p-sidenav__toggle');
var sidebarContent = document.querySelector('.p-sidenav__body');
toggle.addEventListener('click', function(e) {
toggle.classList.toggle('p-icon--menu');
toggle.classList.toggle('p-icon--close');
sidebarContent.classList.toggle('u-hide--small');
});
window.addEventListener("DOMContentLoaded", function() {
// Based on Vanilla side navigation example
// Should be moved out from the template as part of a given project JS
/**
Toggles the expanded/collapsed classed on side navigation element.
@param {HTMLElement} sideNavigation The side navigation element.
@param {Boolean} show Whether to show or hide the drawer.
*/
function toggleDrawer(sideNavigation, show) {
const toggleButtonOutsideDrawer = sideNavigation.querySelector(
".p-side-navigation__toggle"
);
const toggleButtonInsideDrawer = sideNavigation.querySelector(
".p-side-navigation__toggle--in-drawer"
);

if (sideNavigation) {
if (show) {
sideNavigation.classList.remove("is-drawer-collapsed");
sideNavigation.classList.add("is-drawer-expanded");

toggleButtonInsideDrawer.focus();
toggleButtonOutsideDrawer.setAttribute("aria-expanded", true);
toggleButtonInsideDrawer.setAttribute("aria-expanded", true);
} else {
sideNavigation.classList.remove("is-drawer-expanded");
sideNavigation.classList.add("is-drawer-collapsed");

toggleButtonOutsideDrawer.focus();
toggleButtonOutsideDrawer.setAttribute("aria-expanded", false);
toggleButtonInsideDrawer.setAttribute("aria-expanded", false);
}
}
}

// throttle util (for window resize event)
var throttle = function (fn, delay) {
var timer = null;
return function () {
var context = this,
args = arguments;
clearTimeout(timer);
timer = setTimeout(function () {
fn.apply(context, args);
}, delay);
};
};

/**
Attaches event listeners for the side navigation toggles
@param {HTMLElement} sideNavigation The side navigation element.
*/
function setupSideNavigation(sideNavigation) {
var toggles = [].slice.call(
sideNavigation.querySelectorAll(".js-drawer-toggle")
);
var drawerEl = sideNavigation.querySelector(".p-side-navigation__drawer");

// hide navigation drawer on small screens
sideNavigation.classList.add("is-drawer-hidden");

// setup drawer element
drawerEl.addEventListener("animationend", () => {
if (!sideNavigation.classList.contains("is-drawer-expanded")) {
sideNavigation.classList.add("is-drawer-hidden");
}
});

// Add active links to active nav item and scroll to section
var sidebar = document.querySelector(".l-docs-sidebar");
document.querySelectorAll('.p-sidenav__body ul a').forEach(function(anchor) {
if (anchor.pathname === location.pathname) {
anchor.classList.add('is-active');
var section = anchor.closest("ul");
sidebar.scrollTo(0, section.offsetTop - 40);
window.addEventListener("keydown", (e) => {
if (e.key === "Escape") {
toggleDrawer(sideNavigation, false);
}
});

// setup toggle buttons
toggles.forEach(function (toggle) {
toggle.addEventListener("click", function (event) {
event.preventDefault();

if (sideNavigation) {
sideNavigation.classList.remove("is-drawer-hidden");
toggleDrawer(
sideNavigation,
!sideNavigation.classList.contains("is-drawer-expanded")
);
}
});
});

// hide side navigation drawer when screen is resized
window.addEventListener(
"resize",
throttle(function () {
toggles.forEach((toggle) => {
return toggle.setAttribute("aria-expanded", false);
});
// remove expanded/collapsed class names to avoid unexpected animations
sideNavigation.classList.remove("is-drawer-expanded");
sideNavigation.classList.remove("is-drawer-collapsed");
sideNavigation.classList.add("is-drawer-hidden");
}, 10)
);
}

/**
Attaches event listeners for all the side navigations in the document.
@param {String} sideNavigationSelector The CSS selector matching side navigation elements.
*/
function setupSideNavigations(sideNavigationSelector) {
// Setup all side navigations on the page.
var sideNavigations = [].slice.call(
document.querySelectorAll(sideNavigationSelector)
);

sideNavigations.forEach(setupSideNavigation);
}

setupSideNavigations('.p-side-navigation, [class*="p-side-navigation--"]');

// Setup expandable side navigation

var expandToggles = document.querySelectorAll(".p-side-navigation__expand");
var navigationLinks = document.querySelectorAll(".p-side-navigation__link");

// setup default values of aria-expanded for the toggle button, list title and list itself
const setup = (toggle) => {
const isExpanded = toggle.getAttribute("aria-expanded") === "true";
if (!isExpanded) {
toggle.setAttribute("aria-expanded", isExpanded);
}
const item = toggle.closest(".p-side-navigation__item");
const link = item.querySelector(".p-side-navigation__link");
const nestedList = item.querySelector(".p-side-navigation__list");
if (!link?.hasAttribute("aria-expanded")) {
link.setAttribute("aria-expanded", isExpanded);
}
if (!nestedList?.hasAttribute("aria-expanded")) {
nestedList.setAttribute("aria-expanded", isExpanded);
}
};

const handleToggle = (e) => {
const item = e.currentTarget.closest(".p-side-navigation__item");
const button = item.querySelector(".p-side-navigation__expand");
const link = item.querySelector(".p-side-navigation__link");
const nestedList = item.querySelector(".p-side-navigation__list");
[button, link, nestedList].forEach((el) =>
el.setAttribute(
"aria-expanded",
el.getAttribute("aria-expanded") === "true" ? "false" : "true"
)
);
};

expandToggles.forEach((toggle) => {
setup(toggle);
toggle.addEventListener("click", (e) => {
handleToggle(e);
});
});
});
</script>
<script src="/static/js/modules/discourse-rad-parser/discourse-rad-parser.js"></script>
<script>
Expand Down
Loading

0 comments on commit 4462606

Please sign in to comment.