📝 Fix up docs

This commit is contained in:
trickypr 2022-04-10 17:18:42 +10:00
parent d0e6248fd2
commit 41f7b46d93
32 changed files with 33 additions and 621 deletions

26
docs/config.toml Normal file
View file

@ -0,0 +1,26 @@
name = "Gluon"
description = "Build Firefox-based browsers with ease"
license = "MPL 2.0"
homepage = "https://github.com/pulse-browser/gluon"
min_version = "1.14.0"
# The URL the site will be built for
base_url = "https://docs.gluon.dev"
# Whether to automatically compile all Sass files in the sass directory
compile_sass = true
# Whether to build a search index to be used later on by a JavaScript library
build_search_index = true
[markdown]
# Whether to do syntax highlighting
# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
highlight_code = true
[extra]
# TODO: New logo
release = "https://api.github.com/repos/focus-browser/build/releases/latest"
[author]
name = "TrickyPR"

8
docs/content/_index.md Normal file
View file

@ -0,0 +1,8 @@
+++
title = "index"
insert_anchor_links = "right"
+++
## Welcome to the melon docs
If you are new here, you should read the [Getting Started](./getting-started/overview/) guide.

View file

@ -0,0 +1,5 @@
+++
title = "Getting Started"
weight = 1
sort_by = "weight"
+++

View file

@ -0,0 +1,77 @@
+++
title = "Overview"
weight = 5
+++
## Getting started with melon
### What is melon
Melon is a build tool and documentation for creating firefox-based browsers. Its goal is to simplify the process of creating web browsers to encourage competition and development within the space.
### Getting help
If you are having problems with following these instructions, or with melon in general, please contact us. You can [create a discussion on github](https://github.com/dothq/melon/discussions/new), ping @trickypr on the [Dot HQ discord](https://dothq.link/dsc), or [join our Matrix chat](https://dothq.link/matrix).
### System requirements
- **OS**: Linux, Windows, MacOS (We only have active contributors on linux, so other platforms might be a touch buggy)
- **Melon dependencies**: NodeJS and npm
- **Browser dependencies**: TODO: find out what firefox's build dependencies are
### Getting started
The first thing you are going to need to do is to install melon. As it is a nodejs program it can be installed through npm or yarn.
```sh
npm install -g melon-build
# or
yarn global add melon-build
# Note: Linux and mac users may have to run the above command with sudo
```
Now create a git repo and clone it to your local machine. Then run `melon setup-project` inside of that repo. This will ask you a variety of questions in relation to your project setup. Firstly, the release of the browser you want to bind to.
- `Firefox nightly`: Updates every 12 hours, making it almost impossible to keep up to date **(not recommended)**
- `Firefox beta`: Updates every 4 weeks. It will have unresolved bugs **(not recommended)**
- `Firefox developer edition`: Tracks firefox beta **(not recommended)**
- `Firefox stable`: Releases around every 4 weeks, however has most of the bugs from beta fixed
- `Firefox extended support release (newer)`: The latest extended support release. Releases around once every 8 stable cycles (mozilla isn't clear on this). Receives regular small security patches and bug fixes, but no large breaking changes (e.g. [proton](https://www.omgubuntu.co.uk/2021/02/try-firefox-proton-redesign-ubuntu)) between releases.
- `Firefox extended support release (newer)`: The oldest supported extended support release. Maximum security and stability, but will lose support sooner than the newer extended support release.
Dot browser currently uses the stable releases, and keeping up to date can be a struggle with a small development team.
Then next is the version of the browser you want to use. By default melon will populate this with the latest version available, which we recommend using.
Next it will ask for the name of your browser. Avoid references to firefox or other mozilla brands if you can.
Vendor is the company (or solo developer) who is creating the browser.
The appid follows reverse dns naming conventions. For example, DotHQ owns the domain `dothq.co`, so our browser is `co.dothq.browser`. If you do not have a domain, you can use your username / psudomim as the appid, e.g. `trickypr.watermelon`.
Next you need to chose a starting template for your browser. You can go with userchrome, where you apply css changes to firefox or custom html, where you have to write everything (tabs, navigation, search boxes) yourself. We generally recommend userchrome for new users, as it has the lowest learning curve. Additionally, you can chose to use no template.
Now you have created the directory structure for your project, you can build it for the first time. First, ask melon to download the firefox source.
```sh
melon download
```
After the source code has been downloaded, the changes to firefox described in the source code must be applied.
```sh
melon import
```
Finally, you can start building the firefox source code. This takes around an hour and a half on my computer, but the binary output will be cached, making later builds faster
```sh
melon build
```
Now you can finally start the browser!
```sh
melon run
```

View file

@ -0,0 +1,73 @@
+++
title = "Userchrome"
weight = 10
+++
This page will explain the process for applying custom css (or userchrome) to your new browser. I expect you to have already setup melon as described in the overview and have something that looks like the following on your screen.
![Firefox build without branding](https://cdn.statically.io/img/dothq.github.io/f=auto/melon/images/userchrome/css-basic.png)
The firefox window shown above is constructed from (x)html, styled with css and made dynamic with javascript. This means that the entire browser can be styled with custom css, called userchrome.
If you selected the userchrome option when setting up the project, melon will have already created the theme files for you. `src/browser/themes/custom/shared/shared.inc.css` will be included on all platforms, whilst platform specific styles will be included from similar files in `src/browser/themes/custom`.
Additionally, firefox has an equivalent to "inspect element", but for the browser. Click on the hamburger menu, select "More tools", then "Browser toolbox" to open it.
![Browser toolbox](https://cdn.statically.io/img/dothq.github.io/f=auto/melon/images/userchrome/browser-toolbox.png)
## A touch of design
This tutorial will attempt to replicate the design of [SimpleFox by Miguel R. Ávila](https://github.com/migueravila/SimpleFox), without copying its code. I would recommend creating your own visual identity for your browser.
## Squaring the tabs
Firefox's proton made the tabs hover, with mixed reception. Let's reverse that.
Using the select tool (top left of the browser toolbox) select the active tab and look for what element provides the background. In this case it is the `.tab-background` element.
You can scroll down to find the code where the border radius is set. In firefox 91, this is:
```css
.tab-background {
border-radius: var(--tab-border-radius);
margin-block: var(--tab-block-margin);
}
```
Firefox uses css variables for a lot of its properties, meaning we can make the tabs square by setting the border radius to 0. Here, the margin, which makes the tabs "float is set", so setting it to zero will cause them to stop floating. This can be done by adding the following line to `src/browser/themes/custom/shared/shared.inc.css`:
```css
:root {
--tab-border-radius: 0 !important;
--tab-block-margin: 0 !important;
}
```
Rebuilding the browser, the tabs are now slightly closer to how we want them.
![Squared tabs](https://cdn.statically.io/img/dothq.github.io/f=auto/melon/images/userchrome/css-square-tabs.png)
There is this weird padding to the left of the active tab. This is caused by the following css:
```css
.tabbrowser-tab {
min-height: var(--tab-min-height);
padding-inline: 2px !important;
}
```
As mozilla are using `!important` here, we have to use [css priority](https://marksheet.io/css-priority.html) to override it, rather than simply creating our own style with `!important`.
```css
#tabbrowser-arrowscrollbox .tabbrowser-tab {
padding-inline: 0 !important;
}
```
Now, I want to remove the "Nightly" pill in the search bar, along with the background of it. Using the browser toolbox, we can figure out that we have to hide `#identity-icon-box`, remove the border on `#urlbar-background` and set `--toolbar-field-background-color` to the value of `--toolbar-bgcolor`.
![Final browser](https://cdn.statically.io/img/dothq.github.io/f=auto/melon/images/userchrome/css-final.png)
I encourage you to experiment and customize your browser to fit what you want your browser to be.
The source code for this tutorial can be found [here](https://github.com/trickypr/watermelon)

View file

@ -0,0 +1,5 @@
+++
title = "Guides"
weight = 2
sort_by = "weight"
+++

View file

@ -0,0 +1,88 @@
+++
title = "Including addons"
weight = 10
+++
# Including addons
Melon provides an automated system for including extensions in your project. The addons are downloaded and included during the `download` build step. Addons can be included in the project config (`melon.json`).
```json
{
// Your options here
"addons": {
"ublock": {
"id": "uBlock0@raymondhill.net",
"url": "https://github.com/gorhill/uBlock/releases/download/1.39.0/uBlock0_1.39.0.firefox.xpi"
}
}
}
```
Note that the `id` is the gecko application id specified in the `manifest.json`.
```json
{
// ...
"browser_specific_settings": {
"gecko": {
"id": "uBlock0@raymondhill.net",
"strict_min_version": "60.0"
}
}
// ...
}
```
## Specifying location in customizable ui
By default, when an addon with a toolbar button, it will placed next to the hamburger menu. However, you may want to place it somewhere else. To do this, you must change the customizable ui in a similar way to how you would to remove pocket.
You are going to want to open `engine/browser/components/customizableui/CustomizableUI.jsm`. At the top, you want to import the `ExtensionCommon` module.
```js
const { makeWidgetId } = ChromeUtils.import(
'resource://gre/modules/ExtensionCommon.jsm'
).ExtensionCommon
```
Then, at the top add a constant with the id of the addon at the top of the file, for example:
```js
const kUBlockOriginID = 'uBlock0@raymondhill.net'
```
Now, you can go down to the `navbarPlacements` array (around line 240) and add
```js
`${makeWidgetId(kUBlockOriginID)}-browser-action`,
```
To the array where you want the icon to appear, for example:
```js
let navbarPlacements = [
'back-button',
'forward-button',
'stop-reload-button',
Services.policies.isAllowed('removeHomeButtonByDefault')
? null
: 'home-button',
'spring',
`${makeWidgetId(kUBlockOriginID)}-browser-action`,
'urlbar-container',
'spring',
'save-to-pocket-button',
'downloads-button',
AppConstants.MOZ_DEV_EDITION ? 'developer-button' : null,
'fxa-toolbar-menu-button',
].filter((name) => name)
```
Finally, export the changes you have made:
```sh
melon export-file browser/components/customizableui/CustomizableUI.jsm
```

View file

@ -0,0 +1,74 @@
+++
title = "Removing pocket"
weight = 5
+++
# Removing pocket
**Note:** This expects you have melon setup.
## Disabling in firefox.js
The goal of this guide is to disable pocket and remove its icon from the toolbar. The first changes we will need to make is to the firefox.js file located in `engine/browser/app/profile/firefox.js`. Scroll to the lines that include the following settings (around line 1980 in firefox 94):
```js
pref('extensions.pocket.api', 'api.getpocket.com')
pref('extensions.pocket.enabled', true)
pref('extensions.pocket.oAuthConsumerKey', '40249-e88c401e1b1f2242d9e441c4')
pref('extensions.pocket.site', 'getpocket.com')
pref('extensions.pocket.onSaveRecs', true)
pref('extensions.pocket.onSaveRecs.locales', 'en-US,en-GB,en-CA')
```
Delete these lines and replace them with the following:
```js
// Taken from BetterFox user.js
user_pref('extensions.pocket.enabled', false)
user_pref('extensions.pocket.api', ' ')
user_pref('extensions.pocket.oAuthConsumerKey', ' ')
user_pref('extensions.pocket.site', ' ')
```
Next, you will need to remove pocket from the new tab page. You can do this by simply adding the following line to the bottom of `firefox.js`:
```js
user_pref(
'browser.newtabpage.activity-stream.section.highlights.includePocket',
false
)
```
Now you simply need to export the changes made to `firefox.js`:
```sh
melon export-file browser/app/profile/firefox.js
```
## Removing pocket icon from toolbar
Whilst the steps above will have disabled pocket. The pocket icon will still be visible in the toolbar. Instead you must remove it from the CustomizableUI layout. Open `engine/browser/components/customizableui/CustomizableUI.jsm` and find the array that looks like this (around line 240):
```js
let navbarPlacements = [
'back-button',
'forward-button',
'stop-reload-button',
Services.policies.isAllowed('removeHomeButtonByDefault')
? null
: 'home-button',
'spring',
'urlbar-container',
'spring',
'save-to-pocket-button',
'downloads-button',
AppConstants.MOZ_DEV_EDITION ? 'developer-button' : null,
'fxa-toolbar-menu-button',
].filter((name) => name)
```
Remove the `save-to-pocket-button` item from the array and export the changes:
```sh
melon export-file browser/components/customizableui/CustomizableUI.jsm
```

View file

@ -0,0 +1,5 @@
+++
title = "Notes"
weight = 3
sort_by = "weight"
+++

View file

@ -0,0 +1,48 @@
+++
title = "Forcing windows to work"
weight = 10
+++
## Steps followed to get installing on windows to work
1. Install build tools for Visual Studio
- Desktop development with c++
- Windows 10 sdk (at least 10.0.19041.0).
- C++ ATL for v143 build tools (your architecture)
2. Install git for windows: https://git-scm.com/download/win
- Configuring the line ending conversions **must be**: Checkout as-is, commit as-is
- Enable experimental built-in file system monitor
3. Install mozilla build. See mozillas documentation
4. Install Nodejs and yarn - This should install chocoalaty
5. Clone pulse recursivly (cmd)
6. Install dependancies `yarn`
7. Create link `yarn setupLink:win`
8. Disabled anti-malware on 'C:\mozilla-build' and working directory to reduce system load
9. download and init
10. import patches
11. ./mach boostrap in engine
12. choco install make
13. yarn build
14. ./mach build
## Fixing UI bugs
TODO: flesh this out
Without a correct manifest file, windows will report on windows 8 on windows 10 / 11, leading to a variety of UI bugs.
## Notes to future self
- Try running commands in MozillaBuild shell rather than windows cmd
- Tests need to be disabled by default, they take up too much build time
## TODO:
### UI
- [ ] Fix titlebar buttons - Caused by firefox thinking I am on windows 8
### Build
- [ ] Test to see if git in git-bash / mozilla's terminal is faster
- [ ] Use git-bash / mozilla terminal for git
- [ ] Make sure yarn build works

61
docs/sass/_search.scss Normal file
View file

@ -0,0 +1,61 @@
.search-container {
display: none;
&--is-visible {
display: block;
width: 100%;
}
#search {
width: 100%;
display: block;
border:none;
border-left: 1px solid $color;
padding:1px 0;
text-align: left;
line-height: $baseline;
font-size: $font-size;
font-family:$font-family;
color:$color;
background:transparent;
}
#search:focus {
outline:none;
border:none;
}
.search-results {
&__header {
font-weight: bold;
padding: 1rem 0rem;
}
&__items {
margin: 0 2vw;
padding: 0;
list-style: circle;
}
&__item {
margin-bottom: 1rem;
}
&__teaser {
}
}
}
#on_right {
display: block;
text-align: right;
margin-bottom: $baseline;
}
#search-ico {
font-family: 'FabricMDL2Icons';
cursor: pointer;
font-size: $baseline;
line-height: 1;
}

34
docs/sass/_variables.scss Normal file
View file

@ -0,0 +1,34 @@
:root {
--bg: #f9f9f9;
--fg: #222;
--links: #00f;
--hover-links: #c00;
--visited-links: #009;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #333;
--fg: #f9f9f9;
--links: rgb(142, 142, 255);
--hover-links: rgb(204, 101, 101);
--visited-links: rgb(86, 86, 151);
}
}
$baseline: 1.5rem;
$background: var(--bg);
$color: var(--fg);
$links: var(--links);
$hover-links: var(--hover-links);
$visited-links: var(--visited-links);
$font-size: 1.125rem;
$font-family: Segoe UI, system-ui, -apple-system, sans-serif;
$line-height: 1.75;
$code_font: 400 1.125rem/1.75 SFMono-Regular, Consolas, Liberation Mono, Menlo,
monospace;

View file

@ -0,0 +1,40 @@
/*
Your use of the content in the files referenced here is subject to the terms of the license at https://aka.ms/fabric-assets-license
*/
@font-face {
font-family: 'FabricMDL2Icons';
src: url('data:application/octet-stream;base64,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') format('truetype');
}
.ms-Icon {
-moz-osx-font-smoothing: grayscale;
-webkit-font-smoothing: antialiased;
display: inline-block;
font-family: 'FabricMDL2Icons';
font-style: normal;
font-weight: normal;
speak: none;
}
// Mixins
@mixin ms-Icon--ChevronRightSmall { content: "\E970"; }
@mixin ms-Icon--ChromeClose { content: "\E8BB"; }
@mixin ms-Icon--Copy { content: "\E8C8"; }
@mixin ms-Icon--GlobalNavButton { content: "\E700"; }
@mixin ms-Icon--MiniLink { content: "\E732"; }
@mixin ms-Icon--Page { content: "\E7C3"; }
@mixin ms-Icon--ProductRelease { content: "\EE2E"; }
@mixin ms-Icon--Save { content: "\E74E"; }
@mixin ms-Icon--Search { content: "\E721"; }
// Classes
.ms-Icon--ChevronRightSmall:before { @include ms-Icon--ChevronRightSmall }
.ms-Icon--ChromeClose:before { @include ms-Icon--ChromeClose }
.ms-Icon--Copy:before { @include ms-Icon--Copy }
.ms-Icon--GlobalNavButton:before { @include ms-Icon--GlobalNavButton }
.ms-Icon--MiniLink:before { @include ms-Icon--MiniLink }
.ms-Icon--Page:before { @include ms-Icon--Page }
.ms-Icon--ProductRelease:before { @include ms-Icon--ProductRelease }
.ms-Icon--Save:before { @include ms-Icon--Save }
.ms-Icon--Search:before { @include ms-Icon--Search }

340
docs/sass/main.scss Normal file
View file

@ -0,0 +1,340 @@
@import 'variables';
html {
font-kerning: normal;
text-rendering: optimizeLegibility;
scroll-behavior: smooth;
}
body {
margin: $baseline 0;
font-size: $font-size;
font-family: $font-family;
line-height: $line-height;
background: $background;
color: $color;
}
#wrap {
max-width: 800px;
}
@keyframes fade-in {
0% {
opacity: 0;
}
50% {
opacity: 0.8;
}
100% {
opacity: 1;
}
}
a {
&:link {
color: $links;
text-decoration: none;
}
&:hover {
color: $hover-links;
}
&:visited {
color: $visited-links;
}
}
h1 {
font-size: 3rem;
}
h2,
h3,
h4 {
.anchor {
visibility: hidden;
text-decoration: none;
cursor: pointer;
line-height: 1;
color: $color;
}
&:hover {
.anchor {
visibility: visible;
animation: fade-in 0.3s ease-in-out;
font-family: 'FabricMDL2Icons';
}
}
}
pre {
margin: $baseline 0;
border-radius: 4px;
padding: $baseline;
overflow: auto;
position: relative;
code {
background: transparent;
&::after {
content: attr(data-lang);
font-style: italic;
line-height: 1;
opacity: 0.3;
position: absolute;
bottom: $baseline;
right: $baseline;
z-index: 1;
}
}
}
code {
font: $code_font;
}
.copy-code-button {
font-family: 'FabricMDL2Icons';
display: none;
background: $background;
border-radius: 4px;
border: none;
cursor: pointer;
animation: fade-in 0.3s ease-in-out;
font-size: $baseline;
color: $color;
z-index: 10;
position: absolute;
top: $baseline;
right: $baseline;
}
pre:hover .copy-code-button {
display: block;
}
nav {
position: sticky;
height: 92vh;
top: $baseline;
left: $baseline;
bottom: $baseline;
padding-right: $baseline;
width: 20rem;
img {
width: 128px;
}
h1 {
margin: 0;
line-height: 1;
}
}
#toc {
margin-left: calc(#{$baseline} + #{$font-size});
padding: 0;
margin: 0 0 0 $baseline;
font-size: 80%;
li {
color: $color;
margin-left: $font-size;
&::before {
display: inline-block;
content: '';
}
ul {
padding: 0;
}
}
}
main {
display: flex;
flex-flow: row nowrap;
animation: fade-in 0.4s ease-in-out;
}
#release {
text-align: left;
margin: $baseline 0;
&::before {
display: inline-block;
content: '\EE2E';
font-family: 'FabricMDL2Icons';
margin-right: calc(#{$baseline} / 8);
}
}
@keyframes slideIn {
0% {
max-height: 0;
opacity: 0;
}
100% {
max-height: 999px;
opacity: 1;
}
}
@keyframes slideOut {
0% {
height: auto;
opacity: 1;
}
100% {
height: 0;
opacity: 0;
}
}
nav label {
display: block;
}
#trees {
overflow-y: auto;
height: 80%;
}
.subtree {
overflow: hidden;
margin: calc(#{$baseline} / 8) 0;
transition: overflow 0.2s ease-in-out;
padding: 0;
}
.tree-toggle-label {
user-select: none;
cursor: pointer;
}
.tree-toggle-label::before {
display: inline-block;
content: '\E970';
font-family: 'FabricMDL2Icons';
font-size: 0.75rem;
transform: rotate(0deg);
transform-origin: 50% 50% 0px;
transition: transform 0.1s linear 0s;
margin-right: 2px;
}
.tree-toggle {
position: absolute;
opacity: 0;
z-index: -1;
}
.tree-toggle:checked + .tree-toggle-label::before {
content: '\E970';
font-family: 'FabricMDL2Icons';
font-size: 0.75rem;
transform: rotate(90deg);
transform-origin: 50% 50% 0px;
transition: transform 0.1s linear 0s;
margin-right: 2px;
}
.tree-toggle:checked + .tree-toggle-label {
font-weight: bold;
}
.tree-toggle + .tree-toggle-label + .subtree {
animation-name: slideOut;
animation-duration: 0.25s;
animation-fill-mode: both;
}
.tree-toggle:checked + .tree-toggle-label + .subtree {
animation-name: slideIn;
animation-duration: 0.25s;
animation-fill-mode: both;
}
.subtree li {
list-style-type: none;
margin-left: $baseline;
a {
color: $color;
}
&::before {
content: '\E7C3';
font-family: 'FabricMDL2Icons';
font-size: 0.75rem;
}
}
.active a {
font-weight: bold;
}
article {
width: calc(100% - (#{$baseline} * 4 + 20rem));
margin-left: calc(#{$baseline} * 2);
img {
max-width: 100%;
}
}
#mobile {
display: none;
}
@media screen and (max-width: 1023px) {
main {
flex-flow: column nowrap;
width: 100%;
}
nav {
position: inherit;
height: auto;
margin: $baseline $baseline 0 $baseline;
}
article {
width: calc(100% - (#{$baseline} * 2));
margin: 0 $baseline;
z-index: 1;
}
#mobile {
font-family: 'FabricMDL2Icons';
cursor: pointer;
font-size: $baseline;
margin: 0 $baseline 0 0;
display: block;
color: $color;
}
#trees {
display: none;
position: absolute;
background: $background;
height: auto;
width: 100vw;
z-index: 10;
box-shadow: 0 2px 0 rgba(0, 0, 0, 0.1);
}
#on_right {
margin-top: $baseline;
}
}
@import 'fabric-icons-inline';
@import 'search';

1
docs/templates/anchor-link.html vendored Normal file
View file

@ -0,0 +1 @@
&nbsp;<a class="anchor" href="#{{ id }}">&#xE732;</a>

135
docs/templates/index.html vendored Normal file
View file

@ -0,0 +1,135 @@
<!DOCTYPE HTML>
<html>
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="{{ get_url(path="main.css") | safe }}">
{% if config.extra.favicon %}
<link rel="icon" href="{{ config.extra.favicon | safe }}">
{% endif %}
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
<title>{% block title %}{{ config.title }}{% endblock title %}</title>
</head>
<body>
{% if config.extra.release %}
<script>
fetch('{{ config.extra.release | safe }}')
.then((response) => {
return response.json();
})
.then((data) => {
let release_name = data.name;
let html_url = data.html_url;
release.innerHTML = `<a href='${html_url}'>${release_name}</a>`;
});
</script>
{% endif %}
<main>
{% block nav %}
<nav>
{% if config.extra.logo %}
{% if current_path == "/" %}
<img src="{{ config.extra.logo | safe }}" alt="" />
{% else %}<a href="{{ config.base_url }}">
<img src="{{ config.extra.logo | safe }}" alt="" />
</a>
{% endif %}
{% else %}
<h1><a href="{{ config.base_url }}">{{ config.title }}</a></h1>
{% endif %}
{% if config.extra.release %}
<div id="release"></div>
{% endif %}
<a href="javascript:void(0);" onclick="burger()" id="mobile" class="ms-Icon--GlobalNavButton"></a>
<div id="trees">
{% set section = get_section(path="_index.md") %}
{% for p in section.subsections %}
{% set subsection = get_section(path=p) %}
<input class="tree-toggle" type="checkbox" id="{{ subsection.title | slugify }}"
{% if current_path is starting_with(subsection.path) %}checked{% endif %} />
<label class="tree-toggle-label" for="{{ subsection.title | slugify }}">{{ subsection.title }}</label>
<ul class="subtree">
{% for page in subsection.pages %}
<li {% if current_path == page.path %}class="active"{% endif %}>
<a href="{{page.permalink | safe }}">{{page.title}}</a>
</li>
{% if current_path == page.path %}
{% set_global header_count = 0 %}
{% for h2 in page.toc %}
{% set_global header_count = header_count + 1 %}
{% for h3 in h2.children %}
{% set_global header_count = header_count + 1 %}
{% for h4 in h3.children %}
{% set_global header_count = header_count + 1 %}
{% endfor %}
{% endfor %}
{% endfor %}
{% if header_count > 4 %}
<ul id="toc">
{% for h2 in page.toc %}
<li><a href="{{ h2.permalink | safe }}">{{ h2.title }}</a>
{% if h2.children %}
<ul>
{% for h3 in h2.children %}
<li><a href="{{ h3.permalink | safe }}">{{ h3.title }}</a></li>
{% endfor %}
</ul>
{% endif %}
</li>
{% endfor %}
</ul>
{% endif %}
{% endif %}
{% endfor %}
</ul>
{% endfor %}
</div>
</nav>
{% endblock nav %}
<article>
{% if config.build_search_index %}
<div id="on_right">
<span id="search-ico" class="ms-Icon--Search"></span>
</div>
<div class="search-container">
<input id="search" type="search" placeholder="Search as you type...">
<div class="search-results">
<div class="search-results__header"></div>
<ul class="search-results__items"></ul>
</div>
</div>
{% endif %}
<div id="wrap">
{% block content %}
{{ section.content | safe }}
{% endblock content %}
</div>
</article>
</main>
{% if config.build_search_index %}
<script type="text/javascript" src="{{ get_url(path="elasticlunr.min.js") | safe }}" defer></script>
<script type="text/javascript" src="{{ get_url(path="search_index.en.js") | safe }}" defer></script>
<script type="text/javascript" src="{{ get_url(path="js.js") | safe }}" defer></script>
{% endif %}
</body>
</html>

3
docs/templates/page.html vendored Normal file
View file

@ -0,0 +1,3 @@
{% extends "index.html" %} {% block title %} {{ page.title }} | {{ config.title
}} {% endblock title %} {% block content %} {{ page.content | safe }} {%
endblock content %}