mcshelby / hugo-theme-relearn Goto Github PK

Dates in changelog are ill formatted.
Link changelog in README.
Describe release process in separate file

Hello,

I would like to insert plots from Plotly, I have been trying the solutions listed here:
https://mertbakir.gitlab.io/hugo/plotly-with-hugo/

and following the example from here:
https://github.com/kc-tal/hugo-plotly-example

But it doesn't work with the Relearn theme, after adding to the HEAD section in layouts/partials/header.html:

{{ if .Params.plotly }}
    <script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
{{ end }}

and adding layouts/shortcodes/load-plotly.html:

{{ if not ($.Page.Scratch.Get "plotlyloaded") }}
  {{ $.Page.Scratch.Set "plotlyloaded" 1 }}
  <script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
{{ end }}

and layout/shortcodes/plotly:

{{ $json := .Get "json" }}
{{ $height := .Get "height" | default "200px" }}
<div id="{{$json}}" class="plotly" style="height:{{$height}}"></div>
<script>
Plotly.d3.json({{$json}}, function(err, fig) {
    Plotly.plot('{{$json}}', fig.data, fig.layout, {responsive: true});
});
</script>

and setting plotly: true in the front matter and using in the markdown:

{{% load-plotly /%}} {{% plotly json="example.json" height="450px" /%}}

I get this error:

Rebuild failed:

"/Users/emortiz/software/GitHub/package/docs/content/basics/parallelization.md:22:18": failed to extract shortcode: shortcode "%}}" has no .Inner, yet a closing tag was provided

20 ___
21 see:
22 {{% load-plotly /%}} {{% plotly json="example.json" height="450px" /%}}

hugo v0.85.0+extended darwin/amd64 BuildDate=unknown

I am using hugo 0.85 in macOS Catalina

Thanks!

Edgardo

Make labels for notice boxes are technically translatable. At the moment the text is hard coded into the CSS.

This is a copy of matcornic/hugo-theme-learn#334.
This is a copy of matcornic/hugo-theme-learn#128.

I have this theme on a test site at http://example.com/hugo , yet I found in the config.toml if I had as the baseURL = http://example.com/hugo , a lot of the links had ..hugo/hugo in them, so I just have the baseURL as http://example.com

It all works fine except for the 'credits', it should be resolving to http://example.com/hugo/credits , yet it is resolving to http://example.com/credits and of course nothing is displayed. The "credits" link works fine locally, as do all links.

I notice the /credits/ path resolves correctly at https://relearn.netlify.app/credits/

This is no big deal, as I'm slowly replacing a lot of the content with the blog content for the site.

(In all cases, example.com is replaced with the real domain name)

Implement switch to sort in descending order.

Reference: matcornic/hugo-theme-learn#456

A short checklist of things that are sub par with current printing. Some stuff may be browser related, I am on Windows using FF and Chrome (and sometimes IE11 if I'm in a good mood)

• text to big, go with DIN saying 11 to 12 pt
• adjust color for notice boxes
• adjust color for codeblocks
• adjust color for table headers
• sidebar removal (FF)
• next / prev removal
• remove runtime styles to have determinstic print output
• unsticky header

Reference: matcornic/hugo-theme-learn#413

Having a search term of "Alice" active on load of the page in the mermaid-exampleSite will "bomb" the mermaid chart.

This is because the mermaid chart and the execution of text highlightning are executed from different onLoad handlers.

This is a copy of matcornic/hugo-theme-learn#452.

Using distinct icons for notice box types helps color impaired users and even on black/white print outs to differ between different box types.

Sadly, there are issues with mermaid 8.8.0 and versions prior.

• Since version 8.2.0, click events and HTML inside of mermaid graphs are only working if securityLevel="loose" is set during mermaid.initialize. See here.

  Since mermaid 8.7.0 there is a securityLevel="antiscript" that seems to be a good fit for a default configuration in our theme.

• Since mermaid 8.7.0, mermaid.initialize does not carry over its initialized values to a rendered graph. If securityLevel="loose" ist set during our initialization code in footer.html this will not be applied during rendering.

  The official mermaid docs may suffer form the same issue. The <span> tag is renderd as text.

• The mermaid 8.2.x branch suffers from incorrect padding for some nodes.

I tested mermaid 8.6.4 and all the above issues are not observable there. So that's my current favorite until further issues.

In the mean time, there may be mermaid versions newer than 8.8.0 been released that dont't have the mentioned issues. So let's find a working version...

This is referenced of matcornic/hugo-theme-learn#443.

Copy to clipboard has a lot of smaller issues:

• contrast for inline code is bad in notice boxes
• bordering the icon does not work well with bordering of inline code
• hover color on inline code icon is blurred
• hover color on block code is statically set to link color of standard theme

And related to that:

• tooltip misses outline border, especially when displayed over dark background (like block code)
• inline code font size is sized by factor of parent font size, which is a hassle if you want to replicate the size for other elements

Children shortcode can override the style of the used HTML elements to encapsulate each child. In case user decides for a non-list element like div or h2 the resulting HTML is still encapsulated in ul tags. That doesn't make sense semantically.

Solution: add extra parameter to also override the style of the container.

Mermaid uses different techniques to generate text in graphs:

in a native svg element
in a svg foreignObject element that embedds html

Highlightning fails for the first case. This patch avoids highlighting text in those elements.
Highlightning for the second case is preserved with this patch.

For users this may be a bit suprising to sometimes see highlighted text in mermaid graphs and sometimes not.

This is a copy of matcornic/hugo-theme-learn#235.

...to be consistent with the rest of the page structure.

This is necessary to include the generated CHANGELOG.md into the official documentation

• add settings to preserve old features to achieve best compatibility to learn-theme.
• document new settings
• document learn-theme compatiblity settings

The units for attchment size aren't translatable at the moment.

Reference: matcornic/hugo-theme-learn#478

Adapt how the attachments shortcode work by providing a new shortcode resources. Use Hugo's page bundles/resources instead of a custom implementation.

Reference: matcornic/hugo-theme-learn#465
Reference: matcornic/hugo-theme-learn#387
Reference: matcornic/hugo-theme-learn#100

Because of a jquery security vulnerability, we are upgrading to the latest version 3.6.0

https://blog.jquery.com/2020/04/10/jquery-3-5-0-released/

Depending on the site content, there may be issues with self-closing tags that are allowed to have content like div or span. See https://jquery.com/upgrade-guide/3.5/

Reference: matcornic/hugo-theme-learn#512

Having a mix of TOML and YAML in front matter makes copy&pasting setting from one page to another a burden.
Also copying from and to the documenation requires additional care to not make examples invalid.

Because tooling for TOML seem superior (at least in VSCode), lets switch all documentation and front matter settings in the example page to TOML.

Additionally we can get rid of some unnecessary fields like date.

Having multiple box elements in one notice box causes the notice box to visually split into multiple parts instead of show all content inside one box.

This is a copy of matcornic/hugo-theme-learn#476.
This is a copy of matcornic/hugo-theme-learn#402.
This is a copy of matcornic/hugo-theme-learn#152.

The page taxonomy page (eg. https://relearn.netlify.app/tags/) displays the unnessessary singluar name in addition to the plural.

Includes setup, cleanup and rebranding

If a user wants to change colors of the notice box labels in his own theme, this is currently hard to achieve in a future proof way.

This is because color is given to the border-top. Therefore if the theme changes the layout of the boxes and uses a different technique to color the notice labels, the users site will be broken.

````mermaid` blocks don't render all the time.

This is a copy of matcornic/hugo-theme-learn#410

There may be installs that don't use mermaid or are always accessed with an internet connection.

In those cases it could be usefull to load the 1,5Mb of mermaid code via a CDN.

This is a copy of matcornic/hugo-theme-learn#361

From the interface it's pretty non-obvious that the expand section can actually be... expanded.

Reference: matcornic/hugo-theme-learn#426

Adding partial templates menu-pre.html and menu-post.html allows easier customisation of the menu look & feel.

A possible use-case is to add a badge to each menu entry based on a property in that page front matter.

That's already possible with the pre field but that leads to too much duplication as I'd have to write the full HTML for the badge in every page.

The official theme repo requires a reason for the decission to fork the original learn theme.

Reference: gohugoio/hugoThemesSiteBuilder#14

Increase contrast for notice boxes for better accessibility.

This is partly a copy of matcornic/hugo-theme-learn#441.

The option in config.toml for setting a mermaid CDN url is ignored by the code.

Reference: matcornic/hugo-theme-learn#510
Reference: matcornic/hugo-theme-learn#362 (review)

Mermaid generates a width=100% for certain diagram types - e.g the gantt diagram. On a narrow website this may cause a busy graph to be hard to read.

The mermaid docs expose this behaviour, too, as seen here.

Also related to this issue: If mermaid does not generate a width=100% the diagramm may overflow out of view if the browser window is too narrow - without generating scroll bars. This is clearly an issue of our CSS and also affects print output.

Nevertheless I don't have an idea how to fix this in a satisfying way for all users.

This is a copy of matcornic/hugo-theme-learn#257

Mermaid configuration can be difficult for some users because of some options that are meant to be secure and therefore are only settable during mermaid.initialize.

By exposing the whole mermaid config object to our config.toml our users would have all the freedom they may require.

This is a copy of matcornic/hugo-theme-learn#453.

a lot of information is duplicated in the README.md and the exampleSite.

Add more links to the exampleSite documentation and streamline it to other themes README.

Remove release information (to wiki?)

Making content a template would be useful for people who want to do some automatic processing across the whole site. An example of that can be to enable people to add support for wiki-style links (as described here: matcornic/hugo-theme-learn#469) on their own, even if Hugo or the theme don't support it natively.

Another use case would be to create a common footer on each content page as described in matcornic/hugo-theme-learn#514

Because content in chapters is currently centered - which looks bad with more than a couple of words - we'll change this to a justifyied display. This still distinguishes the style from a normal page but with improved readabilty in case of longer text.

Was fixed with #54, but here for reference and changelog generation.

The color of the info notice box is currently green and the note box is blue.

This contradicts international standards where the i symbol (for info) is usually associated with a blue color.

So: Switch colors.

It may be desireable to control the rules for expanding sub-menu items in the menu.

E.g. the exampleSite works as a reference guide while also providing tests for available features. This results in poor documentation eg. the examples of the children shortcode messes up the menu structure.

Reference: matcornic/hugo-theme-learn#511
Reference: matcornic/hugo-theme-learn#439
Reference: matcornic/hugo-theme-learn#437
Reference: matcornic/hugo-theme-learn#414
Reference: matcornic/hugo-theme-learn#325
Reference: matcornic/hugo-theme-learn#155
Reference: matcornic/hugo-theme-learn#88

This is a copy of matcornic/hugo-theme-learn#501.

Since a while, Hugo has its own mechanism for code highlightning.

We will remove the old highlightning code provided by the client-side javascript library highlight.js and all its related files.

This also solves issues introduced by Hugos own highlightning because in our theme we are currently highlighting the code twice leading to unpredictiable results.

This will also fix an issue were light code highlightning themes weren't displayed correctly because our styles are overwriting color information, see matcornic/hugo-theme-learn#187

Another advantage is the huge list of supported languages which by far exceeds our current list.

On the downside, this is a breaking change because our current color theme isn't supported by Hugo.

Reference: matcornic/hugo-theme-learn#371

Right in the process of theme registration, hugo changed the process and moved to the new https://github.com/gohugoio/hugoThemesSiteBuilder repository.

Logo and home button may point to the wrong url in case of a base URL.
Also search result links are broken in case a base URL is given.

Reference: matcornic/hugo-theme-learn#507
Reference: matcornic/hugo-theme-learn#504
Reference: matcornic/hugo-theme-learn#468

Reference: matcornic/hugo-theme-learn#71
Reference: matcornic/hugo-theme-learn#69

• typo in predefined color schemes: --MENU-HOME-LINK-HOVERED-color must be --MENU-HOME-LINK-HOVER-color
• --MENU-HOME-LINK-color and --MENU-HOME-LINK-HOVER-color aren't documented
• homelinks styling isn't documented

Reference: matcornic/hugo-theme-learn#471