matcornic/hugo-theme-learn

Porting Grav Learn theme to Hugo

THIS PROJECT IS DEPRECATED

The project is not maintained anymore. Thanks everyone for helping me on building this theme at the time where there were no good Hugo theme for documentation.

Consider migrating to another theme such as Relearn which seems to be a good maintained alternative.

---

Hugo Learn Theme

This repository contains a theme for Hugo, based on great Grav Learn Theme.

Visit the theme documentation to see what is going on. It is actually built with this theme.

Main features

• Automatic Search
• Multilingual mode
• Unlimited menu levels
• Automatic next/prev buttons to navigate through menu entries
• Image resizing, shadow…
• Attachments files
• List child pages
• Mermaid diagram (flowchart, sequence, gantt)
• Customizable look and feel and themes variants
• Buttons, Tip/Note/Info/Warning boxes, Expand

Installation

Navigate to your themes folder in your Hugo site and use the following commands:

cd themes/
git clone https://github.com/matcornic/hugo-theme-learn.git

Check that your Hugo version is minimum 0.25 with hugo version.

Usage

• Visit the documentation

Download old versions (prior to 2.0.0)

If you need old version for compatibility purpose, either download theme source code from releases or use the right git tag. For example, with 1.1.0

• Direct download way: https://github.com/matcornic/hugo-theme-learn/archive/1.1.0.zip
• Git way:

cd themes/hugo-theme-learn
git checkout tags/1.1.0

For both solutions, the documentation is available at https://github.com/matcornic/hugo-theme-learn/releases/download/1.1.0/hugo-learn-doc-1.1.0.zip

Credits

Many thanks to @vjeantet for the fork docdock. The v2 of this theme is mainly based on his work !

License

Releasing

Somewhat work-in-progress steps to release with gren

• Check all MRs assigned to the milestone are closed or pushed back to another release

• Close the milestone

• Check merged MRs on the milestone have a tag (Bug, Enhancement, etc.)

• Tag and push the repo

  git tag <tag>
  git push origin <tag>

• Generate CHANGELOG.md with gren

  gren changelog  --override --generate --tags=all

• Fix the date for the current release in CHANGELOG.md

• Add the changelog to git and update the tag

  git add CHANGELOG.md
  git commit -m "Ship tag <tag>"
  git push origin master
  git tag -f <tag>
  git push --force origin <tag>

• Generate release with gren

  gren release -t <tag>

hugo-theme-learn's Issues

Chromium 55 / 56 - Scroll Broken

Hi,

Scroll seems really broken with chromium 55 / 56 (ok with 51) --> there's an auto-scrool UP, very strange...

Thks,

Ordering menu

Hi, I'm using the template and in a new site when I run this commands:

hugo new --kind chapter codestyles/index.md
hugo new --kind chapter git/index.md
hugo new --kind chapter features/index.md

And if I try to order assigning a different weigth nothing changes, looks like the other is always the alphabetical A to Z.

I'm new at Go and Hugo maybe im doing something wrong, but seems like not!

Make Hugo-Theme-Learn Multilingual.

Hi;

Thanks to port this awesome theme from grav to hugo.

My hope, question is : How hard would be; and If people have interest for it, to make Hugo-Theme-Learn Multilingual ?

TableOfContent of page not available into menu

Hi!

Is there anyway to display .TableOfContents links into navigation when pages are differents of _index.md ?

I do not found any issues or documentation relative to this.

Strange capitalization issue with search

While entering a search query, the character immediately following a match is capitalized.

In this example, as I type 'introduction' in the search box, the text on the page changes from:

• INtroductIOn
• InTroduction
• IntRoduction
• etc.

Handling more than 2 levels

Search enhancement - position on page

I have implemented search as recommended with lunr-hugo and the indexing works well.

I'm wondering, however, if it's possible for the search to also go to the appropriate place on the target page. When I click on a search result it takes me to the right page but the search result target may be quite far down the page in long documents.

It would be excellent if the search did two extra things:

1. scrolled the page to the appropriate point (or at least section)
2. highlighted the search text

By opening the given file, you should see the property chapter=true on top

hugo new --kind chapter basics/_index.md

By opening the given file, you should see the property chapter=true on top, meaning this page is a chapter.

Although there is chapter.md file in themes/hugo-theme-learn/archetypes, it is not applied to be the archetype for new --kind chapter. The default.md from ~/archetypes is applied instead.

The tutorial doesn't say it - should i copy the folders from themes/hugo-theme-learn to the root folder?

I thought the hugo engine would look into the themes/hugo-theme-learn/archetypes after it checks ~/archetypes, but it doesn't

Use absolute path for screenshot in README

Linking screenshots in the README with relative paths might work on GitHub, but the theme site can't find the screenshot under this path. Consider to use an absolute one instead.

Create shortcode for videos

The left menu disappeared

After the two last PR was merged, the left menu of our documentation vanished.
I rolled back to the revision de8584e and the left menu reappeared.

It seems that the new version is not compatible with an older configuration.

Using icons (from font-awesome) on the pages

When I try to call an icon (using font-awesome) from any of the chapter pages, there is an error parsing the html!
Sample code:
+++
weight = 0
title = "Some Chapter title"
chapter = true
next = "/next/path"
icon = "<i class="fa fa-check"></i>"
+++

Am I calling the icon correctly, or should I have a local copy of font-awesome in the project?

use .Site.BaseURL for assets

all assets have hardcoded paths like /css should be baseurl related

Update to Hugo version 0.23

Starting with Hugo version 0.22 .Site.Sections is not working anymore. Switch to proposal from

https://github.com/gohugoio/hugo/blob/master/hugolib/site_sections.go#L34

[Shortcode] Tabs

Hello,

Please add horizontal tabs. This feature is useful for an API documentation to give code sample for multiple languages (ex: Shell, Python, Java, ...)

Search enhancements

Hi!

1. Is Search not working on mobile? Tested with Android/Chrome and nothing pops up during the characters typing in the search field

2. Search on a desktop appears only as a drop down with top-10 results. Is it possible to rather display a page with search results where >10 items could be displayed?

Fix Hugo Demo site

The Demo button for the preview of this theme does not work. It'd be neat if you could fix so more people use the theme.
http://themes.gohugo.io/theme/hugo-theme-learn/

[Shortcode] Set an "Expand" item open by default

Hello,

It would be nice to have hability to set "expand" item open by default.

By example:

{{%expand "Open by default?"  true %}}Yes!{{% /expand%}}

{{%expand "Open by default?"  false %}}No!{{% /expand%}}

Support same page anchor like ReadTheDocs

Hello

I'm wondering if this theme support same page anchor link.
Something like: https://borgbackup.readthedocs.io/en/stable/installation.html
Where the menu point to the title on the same page, if that make any sense...

Kristian

Q. about TableOfContents

Hi,

You define TableOfContents in hugo-theme.css without using it (it's display:none). Do you plan to use it by configuration ?

Thks a lot

Issue on page resize

A horizontal scrollbar appear on the bottom of the page when the browser is resized. Same issue with Opera / Chrome and Firefox. Maybe the issue come from a JS code...

1. Maximize your browser window
2. Go to https://learn.netlify.com/en/cont/archetypes/
3. Resize your window to enter "mobile" version
4. Scroll to bottom
5. Bugged horizontal scrollbar (see picture)
6. Refresh page
7. Bugged horizontal scrollbar disappear

Create new documentation website from scratch

• Auto deployment on Netlify
• Create documentation in english with new features of v2
• Create documentation in french with new features of v2

Error rendering partial in menu.html

I'm getting an error with Hugo v0.20.7 and hugo-theme-learn bc05a6e.

This was from following the setup instructions here: https://matcornic.github.io/hugo-learn-doc/basics/installation/

---

$ /opt/hugo/hugo serve

Started building sites ...

ERROR 2017/05/14 19:13:36 Error while rendering "section": template: theme/_default/list.html:2:3: executing "theme/_default/list.html" at <partial "header.html...>: error calling partial: template: theme/partials/header.html:26:7: executing "theme/partials/header.html" at <partial "menu.html" ...>: error calling partial: template: theme/partials/menu.html:20:28: executing "theme/partials/menu.html" at <$sectionPage.Content>: can't evaluate field Content in type *hugolib.Page

ERROR 2017/05/14 19:13:36 Error while rendering "page": template: theme/_default/single.html:1:3: executing "theme/_default/single.html" at <partial "header.html...>: error calling partial: template: theme/partials/header.html:26:7: executing "theme/partials/header.html" at <partial "menu.html" ...>: error calling partial: template: theme/partials/menu.html:20:28: executing "theme/partials/menu.html" at <$sectionPage.Content>: can't evaluate field Content in type *hugolib.Page

---

Any ideas? Thanks!

Scroll Issue with Chrome

Your theme is very nice, but Chrome presents a scroll issue.

This issue does not occur in MS Edge or Firefox.

Essentially if you scroll down in Chrome, the page then tries to scroll back up[ to the top.

Clearly a Javascript issue ( disabling JS in chrome make the problem go away ). Console shows no JS errors.

I tried looking at your code, but you are doing several clever things relating to window height and scroll so couldn't easily identify the exact issue.

Weird cache on Netlify

Image with "?classes=xxx" are not displayed in Netlify documentation.

Consider moving back to Github Pages.

Search input clear button doesn't work

I'm not able to get the search input's clear button to work.

It seems the code to register the click handler is never getting hit.

I really don't know jQuery, but I can tell from playing in the debugger that none of the code inside the on('input', ...) handler is being run.

    jQuery('[data-search-input]').on('input', function() {
        var input = jQuery(this),
            value = input.val(),
            items = jQuery('[data-nav-id]');
        items.removeClass('search-match');
        if (!value.length) {
            $('ul.topics').removeClass('searched');
            items.css('display', 'block');
            sessionStorage.removeItem('search-value');
            $(".highlightable").unhighlight({ element: 'mark' })
            return;
        }

        sessionStorage.setItem('search-value', value);
        $(".highlightable").unhighlight({ element: 'mark' }).highlight(value, { element: 'mark' });

        if (ajax && ajax.abort) ajax.abort();
        ajax = jQuery.ajax({
            url: input.data('search-input') + ':' + value
        }).done(function(data) {
            if (data && data.results && data.results.length) {
                items.css('display', 'none');
                $('ul.topics').addClass('searched');
                data.results.forEach(function(navitem) {
                    jQuery('[data-nav-id="' + navitem + '"]').css('display', 'block').addClass('search-match');
                    jQuery('[data-nav-id="' + navitem + '"]').parents('li').css('display', 'block');
                });
            }
            ;

        });
        jQuery('[data-search-clear]').on('click', function() {
            jQuery('[data-search-input]').val('').trigger('input');
            sessionStorage.removeItem('search-input');
            $(".highlightable").unhighlight({ element: 'mark' })
        });
    });

The first line in this code block is being hit, but nothing inside it (including the registration of the clear button's click handler) is running.

Function slice not defined and menu.html is incomplete

First of all, great theme!

I am getting below errors.

chankeypathak@perl:~/Desktop/chankeypathak/test$ hugo server --buildDrafts --theme=hugo-theme-learn --buildDrafts
ERROR: 2016/11/29 15:33:03 template.go:350: template: theme/partials/menu.html:16: function "slice" not defined
ERROR: 2016/11/29 15:33:03 template.go:119: html/template: "theme/partials/menu.html" is an incomplete template in theme/partials/menu.html
1 of 1 draft rendered
0 future content
1 pages created
0 non-page files copied
0 paginator pages created
0 tags created
0 categories created
in 14 ms
Watching for changes in /home/chankeypathak/Desktop/pproj/test/{data,content,layouts,static,themes}
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Search error with _index.md pages

when using search, subpages work fine but when the search result points to a chapter index page, the link is incorrect.

For example,

1. search for core in the site http://matcornic.github.io/hugo-learn-doc
2. click on the search result Basics

This will result in the wrong URL being served for the search, ie:
https://matcornic.github.io/hugo-learn-doc/basics/_index
NOT
https://matcornic.github.io/hugo-learn-doc/basics

Is there a simple way to fix this behaviour?

Minor Graphical Issue

Hi I found some stranges in my page.

See below image

When I choose the menu "security" which under the "Container" menu.
Another menu entry "Securiy" also be highlighted and opened, if I checked before.

Any idea why it works like that ?

Is it possible to redirect from one page to another?

Hi there,

I work on the documentation team at Miracl.com. We're thinking of moving our documentation to Hugo but have a requirement for redirects to be set up from chapter pages, so users don't have to read perfunctory intro. text. Is this technically possible? If so, how would I go about doing it?

To be more specific, if say a visitor clicks on a chapter named "Registering" containing two sub-pages, one with Android instructions and one with iOS instructions, the visitor should be taken directly to the first sub-page, /registering/registering-android rather than its parent, /registering. Hope that makes sense!

Thanks,

Matt

Failed to render "editURL"

the editURL is not rendered properly

below is my config.toml

[params]
  description = "hugo contents for keyolk.github.io"
  author = "keyolk"
  showVisitedLinks = true
  search = true
  editURL = "https://github.com/keyolk/keyolk.github.io-hugo/edit/master/content/"
  menu = [ "workspace", "container", "system", "security", "language", "algorithm" ]

It works after I change below

diff --git a/layouts/partials/header.html b/layouts/partials/header.html
index 030139c..1f91f71 100644
--- a/layouts/partials/header.html
+++ b/layouts/partials/header.html
@@ -29,12 +29,12 @@
         <div class="padding highlightable">

             <div id="top-bar">
-              {{ if and .IsPage .Site.Params.editURL }}
+              {{ if and .IsPage .Site.Params.editurl }}
                 {{ $File := .File }}
                 {{ $Site := .Site }}
                 {{with $File.Path }}
               <div id="top-github-link">
-                  <a class="github-link" href="{{ $Site.Params.editURL }}{{ replace $File.Dir "\\" "/" }}{{ $File.LogicalName }}" target="blank">
+                  <a class="github-link" href="{{ $Site.Params.editurl }}{{ replace $File.Dir "\\" "/" }}{{ $File.LogicalName }}" target="blank">
                     <i class="fa fa-code-fork"></i>
                     Edit this page
                   </a>

I'm not sure, it seems the pram names is used with lower case when it templated.

$ hugo version
Hugo Static Site Generator v0.17 BuildDate: 2016-12-18T03:13:22-08:00

Language selector does not work with sub-folders in baseURL

See https://themes.gohugo.io/theme/hugo-theme-learn/en

Configuration of the appearance of the copy-to-clipboard icons

Thanks for a great Hugo theme!

For my site I don't want the copy-to-clip-board icon for inline code tags but keep it for code tags within pre tags. I was able to achieve this by adding this css:

:not(pre) > code + span.copy-to-clipboard {
    display: none;
}

It would be really handy if it would be possible to configure the appearance of the copy-to-clipboard icons from the config.toml file. Maybe this could be considered for future versions of the theme.

h5 font size property incorrect

Hi there,

I see in the hugo-theme.css file the definition of h5 elements is

h5 {
  font-size: 1;
  line-height: 110% !important;
  margin: 1rem 0 0.2rem 0;
}

This results in the h5 not being rendered correctly. Firefox's dev tools shows the property is invalid because no units have been specified.

I think this should be changed to follow the other h2...h4 definitions that use rem units, so:

font-size: 1rem;

Searching in all the site

Codeblock with horizontal scrollbar

Hi,

first of all i a really like your theme.

Is it possible to add a Codeblock with horizontal Scrollbars, e.g. as a shortcode?

Theme does not support baseurl with path component

This theme does not support deployment to baseurls which include a path component such as http://username.github.io/repo since assets are referred to as absolute paths.

Asciidoc/Asciidoctor support ?

Does the theme support asciidoc well ?

I am searching for a technical documentation site generator that supports that format.

Thanks for your help.

Cheers

Add optional button to create an issue on a page

Like the "Edit this page" button, we could have a "Create an issue" button for a page. It could be used to create an issue for missing/wrong information.

How to configure the menu from config.toml

Using this theme I can successfully add a weight in the page front-matter.

Usually the menu for a Hugo site can also be configured from the config.tom file by adding entries to [[menu.main]], see https://gohugo.io/extras/menus/

But, for this theme this does not work, is there another way to configure the menu from config.toml?

Hugo version: 0.21

Busting javascript cache

As Javascript/css files are cached in browser, errors may occurs on the browser when Javascript has been updated on the server but not on the client.

In order to do that, a simple solution is to change the filename when file has changed.

https://discuss.gohugo.io/t/cache-busting-of-css-js/175

Change the shortcode relref to handle i18n

Overwritten relref shortcode does not handle well multilang

Edit: Some tests were done, and it appears not using i18n is also problematic for links between pages.

strange bug on sidebar menu in the demo

When I go to https://learn.netlify.com/fr/shortcodes/expand/ page, the children section in the menu display the wrong pages.

Logo question

Hi,
sorry if this is a dumb question, but how can I change the logo and still make it fit?
Thanks!

Is it possible to create globally available variables?

Is it possible to create a global variables (useful for global links)?
For instance throughout my documentation articles I refer to my master branch, and I want to have it as a variable, rather than pasting an absolute link.

refer to this example

[my repo][my_repo_link]

[my_repo_link]: {{params.my_global_repo_link}}

This is possible in gitbook for instance and has a huge importance as to my opinion. Could it be that I can put something in [params] and use it like that?

Cant render header on taxonomy page

Hi I got below error while I'm trying to use taxonomy.

ERROR: 2017/01/15 22:32:49 template.go:132: template: theme/partials/header.html:24:30: executing "theme/partials/header.html" at <.RelPerma
link>: can't evaluate field RelPermalink in type *hugolib.Node in theme/partials/header.html
ERROR: 2017/01/15 22:32:49 template.go:132: template: theme/partials/header.html:24:30: executing "theme/partials/header.html" at <.RelPerma
link>: can't evaluate field RelPermalink in type *hugolib.Node in theme/partials/header.html

Seems it related to
https://discuss.gohugo.io/t/cant-evaluate-field-relpermalink-in-type-hugolib-node/4280/3

Any of workaround ?

$ hugo version
Hugo Static Site Generator v0.17 BuildDate: 2016-12-18T03:13:22-08:00

Use mermaid to generate flowcharts from text

Problems with search

I have tried implementing search using the following method, but the search bar does not appear in the site.
I'm wondering if I'm missing a step?

---

1. install hugo-theme-learn
2. create Gruntfile.js in the root (slightly modified from https://gist.github.com/sebz/efddfc8fdcb6b480f567)

var toml = require("toml");
var S = require("string");

var CONTENT_PATH_PREFIX = "content";

module.exports = function(grunt) {

    grunt.registerTask("lunr-index", function() {

        grunt.log.writeln("Build pages index");

        var indexPages = function() {
            var pagesIndex = [];
            grunt.file.recurse(CONTENT_PATH_PREFIX, function(abspath, rootdir, subdir, filename) {
                grunt.verbose.writeln("Parse file:",abspath);
                pagesIndex.push(processFile(abspath, filename));
            });

            return pagesIndex;
        };

        var processFile = function(abspath, filename) {
            var pageIndex;

            if (S(filename).endsWith(".html")) {
                pageIndex = processHTMLFile(abspath, filename);
            } else {
                pageIndex = processMDFile(abspath, filename);
            }

            return pageIndex;
        };

        var processHTMLFile = function(abspath, filename) {
            var content = grunt.file.read(abspath);
            var pageName = S(filename).chompRight(".html").s;
            var href = S(abspath)
                .chompLeft(CONTENT_PATH_PREFIX).s;
            return {
                title: pageName,
                href: href,
                content: S(content).trim().stripTags().stripPunctuation().s
            };
        };

        var processMDFile = function(abspath, filename) {
            var content = grunt.file.read(abspath);
            var pageIndex;
            // First separate the Front Matter from the content and parse it
            content = content.split("+++");
            var frontMatter;
            try {
                frontMatter = toml.parse(content[1].trim());
            } catch (e) {
                conzole.failed(e.message);
            }

            var href = S(abspath).chompLeft(CONTENT_PATH_PREFIX).chompRight(".md").s;
            }

            // Build Lunr index for this page
            pageIndex = {
                title: frontMatter.title,
                tags: frontMatter.tags,
                href: href,
                content: S(content[2]).trim().stripTags().stripPunctuation().s
            };

            return pageIndex;
        };

        grunt.file.write("static/json/search.json", JSON.stringify(indexPages()));
        grunt.log.ok("Index built");
    });
};

3. test that index exists in static/json/search.json, yes, here's an example index:

[{"title":"Some Chapter title","href":"/introduction/_index","content":" Chapter X Some Chapter title Lorem ipsum"},{"title":"About","href":"/introduction/about_us","content":" testing lets see if we get auto update OK"}]

4. enable search in config.toml

languageCode = "en-us"
title = "Docs"
baseurl = "https://my.url"
theme = "hugo-theme-learn"
search = "true"

Search pop-up does not show on Android+Chrome

Help Wanted, I don't have an Android phone 😄

Automatically generate prev/next

Is it possible to automatically generate the prev and next paths in the front matter?

I'm working on a site with a lot of content and manually setting these on each page is not feasible. Is there some way to automatically generate the links (alphabetically ordering them, perhaps)?