jgazeau / shadocs Goto Github PK

What is missing in the project?

Code should be formatted using prettier. For Go templating use the prettier-plugin-go-template

Solution?

No response

What is missing in the project?

I just got aware of your theme, great work!
I realized that your theme

• is not a hugo module yet.
• is based on bulma framework, which is pulled in as git submodule.

Solution?

My proposal is to transform the theme to a hugo module. Then you can pull in bulma framework as hugo module, which makes update of this dependency even easier.
A while ago, I authored a pull request that did exactly that for the hugo-fresh theme (which is based on bulma too). The theme author accepted my PR and we got it merged. Let me know if you are interested in receiving a similar PR for your shadocs theme. I'm happy to step in and assist you here!

Steps that lead to the issue

• create a new hugo skeleton site (`hugo new site issue-155)
• in config.toml, assign shadocs theme
• add index pages for French, English and German (hugo new content/french/index.md, ...)
• declare the site as multilingual with three pages:

[Languages]
  [Languages.en]
    contentDir   = "content/english"
    title        = "Shadocs theme documentation"
    weight       = 1
    languageName = "English"

  [Languages.fr]
    contentDir   = "content/french"
    title        = "Documentation du thème Shadocs"
    weight       = 2
    languageName = "Français"

  [Languages.de]
    contentDir   = "content/german"
    title        = "Dokumentation für das Theme Shadocs"
    weight       = 2
    languageName = "Deutsch"

Now start preview via hugo server.

Use the language switcher: it shows weird behaviour, you cannot switch properly to all three languages.

Expected behavior

Language switcher should behave correctly and switch properly to all three languages.

Reproducer

I can provide a GitHub repo for reproduction if needed. I don't think that is necessary, though.

Solution?

No response

Question?

I would like to be able to use this theme, it is pretty incredible and the documentation is great! Thank you!!

My deployment mechanism doesn't allow for submodules or hugo modules, so I am needing to create the themes/shadocs files and push during deployment.

I tried via downloading the zip but it seems to be missing quite a bit. Is it possible this could be updated? (example layout/partial/helpers)

I am trying via git clones of this project and the bulma project, but this is requiring identifying/removing all of the module/submodule pieces.

If there is another method that would be more simple please let me know.

Thank you.

Dear Jordan,
I just wanted to say that I am absolutely delighted with your work.
I was looking now for 2 years for the best Hugo Theme I could use for my many documentation sets I have created along many large scale projects for customers and private one. Your ShaDocs Theme is the best for my purpose. Especially the functionality is unbeaten. So, I will fully build on this and I am hoping that many others will use your excellent work as well.
Wish you all the best and whenever you need a reference, count on me.
Your work is simply great.
Thank you!!

What is missing in the theme?

When parsing markdown links, Shadocs will use the relLangURL function to resolve URLs. A problem with this is that the function does not handle links relative to the current page. relref might be used instead, but it does not correctly handle external links.

It appears that the convention in Hugo is to leave links rendered from markdown as-is, and use the ref/relref shortcodes when linking to other pages on the website. Shadocs seems to go against this convention by parsing and handling links rendered by markdown, which is admittedly rather convenient. However, because relLangURL is used to resolve links, the resulting URL is naively relative to the configured baseURL, making it unsuitable for relative paths. The relref function is smarter about this, but it doesn't work with external links. Neither function can be used on its own.

To resolve this problem, the link renderer could parse the URL. If it has a scheme, then relLangURL is used as before. Otherwise, relref is used. To implement this for my website, I made the following change:

Anaminus@7982a49

I'm hesitant to submit this as a Pull Request because links with relative paths are likely to be interpreted differently. Accepting this change would involve users reevaluating all the links on their website, to make sure they are corrected for the new behavior. The effect is wide-reaching enough that it could be considered a breaking change.

What is missing in the project?

Shadocs theme supports tabbed panes, but this can be easily overlooked:

• tab shortcode is not documented at all,
• snippet shortcode acts as container for child tabs (represented by tab shortcodes) but name of the shortcode does not reflect this at all.

I think there is room for improvement here. Why don't we split up the current snippet shortcode into two separate shortcodes:

• tab-container shortcode: to be created
• snippet shortcode: all current snippet functionality, except for nested shortcode support.

Afterwards, the documentation should be reworked to reflect these changes

WDYT?

Solution?

No response

What is missing in the project?

This feature is a bit strange. Since I want to collapse the sidebar, I definitely want to see more article areas, but every time I switch articles, I have to collapse it once.

Solution?

No response

Error: Error building site: TOCSS: failed to transform "css/main.sass" (text/x-sass): SCSS processing failed: file "stdin", line 3, col 1: File to import not found or unreadable: bulma.

Steps that lead to the issue

Open https://shadocs.netlify.app/shortcodes/openapi/
Press some link inside "On this page"

Expected behavior

The pages should scroll to the fragment

Reproducer

See above

Solution?

Add

<script>window.noZensmooth = true;</script>

before loading the swagger-ui javascript files.

What is missing in the theme?

On the smallest desktop screen size (just above 1024px), I feel that the content of a page is squeezed too much by the sidebar and the Table of Contents:

Moreover, the difference between just above 1024px and just below is rather large:

First, I think the ToC should have the same behavior as the sidebar, where on smaller screen sizes, it is collapsed by default, and floats over the page content when expanded.

Second, I think layout responsiveness would be improved by having one panel collapse before the other. The lower-priority panel would begin collapsing on desktop screen sizes, while the higher-priority panel would begin collapsing on touch screen sizes.

I'm not sure which is objectively better, but personally, I like having the ToC collapsed first, which is similar to the workaround I've been using for my website (example).

Steps that lead to the issue

x

Expected behavior

x

Reproducer

x

Solution?

s|https://gohugo.io/content-management/multilingual|https://gohugo.io/content-management/taxonomies|1 exampleSite/content/english/functionalities/taxonomies.md

Steps that lead to the issue

From the root of shadocs repo:

cd exampleSite
hugo server

An error is thrown:

Error: error building site: "/home/andreas/shadocs/exampleSite/content/english/shortcodes/snippet.md:69:13": failed to render shortcode "snippet": failed to process shortcode: "/home/andreas/shadocs/layouts/shortcodes/snippet.html:115:89": execute of template failed: template: shortcodes/snippet.html:115:89: executing "getSnippetContent" at <.context.Page.RenderString>: error calling RenderString: "/home/andreas/shadocs/exampleSite/content/english/shortcodes/snippet.md:1:1": failed to parse Markdown attributes; you may need to quote the values

Expected behavior

No error, site should be served.

Reproducer

This this failed deployment log on Netlify, belonging to #178.

Solution?

This is most likely related to this open isssue in the repo of Hugo SSG. You may wait for a fix or implement a workaround.

Steps that lead to the issue

when I add a custom footer inside the layout custom-footer.html its showing right side in body.

Expected behavior

Footer should be in bottom of the container. There is a missing column inside the main.html

Reproducer

??

Solution?

Yes, Including new columns inside the columns(Nested column) i solved it to bring the custom footer in bottom of the content.

    <div class="columns is-mobile is-paddingless is-marginless"
    id="mainContainer">
         sidebar
         content
      <div class="columns">
        <div class="column">
           includes-end
          custom-footer
        </div>
      </div>
  </body>

Steps that lead to the issue

1. Publish the exampleSite with gitlab pages, you will get a access url like: https://site.pages.example.com/homepage/
2. access url using it
3. click globalLogo, it will return 404, redirected to https://site.pages.example.com/, but not https://site.pages.example.com/homepage/

Expected behavior

You can normally jump to the home page with a relative path

Reproducer

1. publish exampleSites using gitlab pages or github pages
2. access pages
3. click globalLogo

Solution?

No response

What is missing in the project?

please include dark theme in theme

Solution?

No response

Steps that lead to the issue

1. I build a new site with hugo new site xxx
2. Then I follow the doc

cd ${PROJECT_DIRECTORY}
git submodule add https://github.com/jgazeau/shadocs.git themes/shadocs
git submodule update --init --recursive

3. Next I use themes\shadocs\exampleSite\config.toml as site config
4. Finally run hugo server error
   

Expected behavior

I don't konw what's wrong?
How to solve these problems?
Please help me. Thank you!

Reproducer

hugo.exe server
Start building sites …
hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended windows/amd64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio
ERROR 2023/04/21 17:01:50 render of "taxonomy" failed: "E:\web\c\themes\shadocs\layouts_default\terms.html:1:4": execute of template failed: template: _default/terms.html:1:4: executing "_default/terms.html" at <partial "main.html" (dict "root" . "contentTemplate" "theme/terms-content.html")>: error calling partial: "E:\web\c\themes\shadocs\layouts\partials\main.html:5:8": execute of template failed: template: partials/main.html:5:8: executing "partials/main.html" at <partial "theme/includes-head.html" .root>: error calling partial: "E:\web\c\themes\shadocs\layouts\partials\theme\includes-head.html:68:36": execute of template failed: template: partials/theme/includes-head.html:68:36: executing "includeSass" at <append (resources.Get .)>: error calling append: reflect: call of reflect.Value.Type on zero Value
ERROR 2023/04/21 17:01:50 render of "home" failed: "E:\web\c\themes\shadocs\layouts_default\index.html:1:4": execute of template failed: template: _default/index.html:1:4: executing "_default/index.html" at <partial "main.html" (dict "root" . "contentTemplate" "theme/content.html")>: error calling partial: "E:\web\c\themes\shadocs\layouts\partials\main.html:5:8": execute of template failed: template: partials/main.html:5:8: executing "partials/main.html" at <partial "theme/includes-head.html" .root>: error calling partial: "E:\web\c\themes\shadocs\layouts\partials\theme\includes-head.html:68:36": execute of template failed: template: partials/theme/includes-head.html:68:36: executing "includeSass" at <append (resources.Get .)>: error calling append: reflect: call of reflect.Value.Type on zero Value
Error: Error building site: failed to render pages: render of "taxonomy" failed: "E:\web\c\themes\shadocs\layouts_default\terms.html:1:4": execute of template failed: template: _default/terms.html:1:4: executing "_default/terms.html" at <partial "main.html" (dict "root" . "contentTemplate" "theme/terms-content.html")>: error calling partial: "E:\web\c\themes\shadocs\layouts\partials\main.html:5:8": execute of template failed: template: partials/main.html:5:8: executing "partials/main.html" at <partial "theme/includes-head.html" .root>: error calling partial: "E:\web\c\themes\shadocs\layouts\partials\theme\includes-head.html:68:36": execute of template failed: template: partials/theme/includes-head.html:68:36: executing "includeSass" at <append (resources.Get .)>: error calling append: reflect: call of reflect.Value.Type on zero Value
Built in 28 ms

Solution?

No response

Maybe this is stupid - but following basic instructions and adding Bulma from NPM produces this result.

hugo v0.88.1+extended darwin/amd64 BuildDate=unknown
Error: Error building site: TOCSS: failed to transform "css/main.sass" (text/x-sass): SCSS processing failed: file "stdin", line 3, col 1: File to import not found or unreadable: bulma.

Steps that lead to the issue

This is the code from pages with theme shadocs.

Expected behavior

this is rendered using typora

Reproducer

It seems no one can be rendered in my environment, if there is something i should config?

Solution?

No response

When the base URL of the website is configured with a path, the path portion of the logo's URL will be duplicated.

Reproduction:

1. In config.toml, set the baseURL to "https://example.com/foo/bar".
2. Start hugo serve.
3. Navigate to http://localhost:1313/foo/bar/.
4. Click on the logo.

The result is that the page incorrectly navigates to http://localhost:1313/foo/bar/foo/bar/ instead of http://localhost:1313/foo/bar/.

The problem occurs in layouts/partials/theme/logo.html, and is likely caused by passing the .Site.Home.RelPermalink variable to the relLangURL function. Because relLangURL will already include the root, it would appear to be sufficient to pass an empty string instead. For example:

{{"" | relLangURL}}

Because both info alerts and links are blue, a link within an info alert has poor readability. For example, on the page for shortcodes:

Steps that lead to the issue

when generating the site and testing it the sidebar is always expanded on tablet and always minimized on the mobile phone. also the bottom collapse “button” not showing. this is also present in the documentation site when viewed on a mobile device or tablet.

any suggestions for fixing it as i’m not a developer or will there be a fix soon?

Expected behavior

expected the sidebar to be responsive but this issue is not resolved.

Reproducer

the documentation site if viewed on a mobile or a tablet will show the issue.

Solution?

No response

This is part support question and part feature request.

Is there a way to disable the table of contents, sitewide or at the page level? I'd like for the content of some pages to span the full page width, and only use the TOC for pages with long text content.

I'm able to achieve this sitewide by changing {{$.Scratch.Set "isToc" true}} to {{$.Scratch.Set "isToc" false}} in the content.html partial, then changing the width in css from calc(100% - 300px) to 100%. Is there a better way to do this? And is there a way to do it at the page, rather than site, level?

It would be nice to have a sitewide option in the config params, as well as a way to enable/disable the TOC at the page level by configuring it in the page metadata.

If this configurability can be achieved, it would then be even better to also let the TOC be collapsible like the left sidebar on pages where it's enabled.

Have installed current Shadocs Theme from GitHub into most updated HUGO instance on my local Windows10 machine.
Have then copied the Theme's Example Project intp the root-folder

Problem:

When hugo generating I have got the following error message:

"C:\me\...\TestSite\content\english\_index.md:8:1": failed to extract shortcode: template for shortcode "intro" not found"

This error is most probably due to a path issue: because the intro.md template file is available but cannot be found.

Solution:

In config.toml - which I have copied form the Example Projcet as well - I have removed the themesdir = "../.." statement. After this all fine

Question:
Not sure whether this is really the way to go. Could you pls have a look into this. Thanks.

Question?

Hello, in first thank you for this great theme. I just discovered it, and it answers to my needs :)

It's seems that Search functionality does not run in my project (not published yet on Internet).

• Shadoc site, Search Functionality is OK.
• Once theme installed, Exemple Site ran locally hugo -s exampleSite/ server Serach Functionality is KO (fresh install) no modifications on hugo.toml file done.
• On my project Search Functionality is KO
• All other functionalities are running well : intro, print, shortcuts (except search), info....

Please below my hugo.toml ; i did not updated or replaced any themeParams.toml in theme/shadocs/data/themeParams.toml

Did I make a configuration error ?

Thank you in advance.

My hugo.toml

defaultContentLanguage` = "fr"
metaDataFormat         = "yaml"
title                  = "0liv's blog"
theme                  = "shadocs"

[taxonomies]
  category = "categories"
  tag = "tags"

[outputs]
  home = ["HTML", "JSON"]

[markup]
  defaultMarkdownHandler = "goldmark"
  [markup.tableOfContents]
    ordered    = false
    startLevel = 1 # start level for toc
    endLevel   = 6 # end level for toc
  [markup.goldmark.renderer]
    unsafe = false

[Languages]
  [Languages.fr]
    contentDir   = "content/fr"
    title        = "Le blog de 0liv"
    weight       = 1
    languageName = "Français"

  [Languages.en]
    contentDir   = "content/en"
    title        = "0liv's blog"
    weight       = 2
    languageName = "English"

[params]
  logo                    = "images/logo.png"
  logoTouch               = "images/logoTouch.png"
  image404                = "images/404.gif"
  favicon                 = "images/favicon.png"
  faviconmd               = "![Favicon](/images/favicon.png)"
  homeLayout              = "onboarding"
  siteContentOrder        = "weight"
  toc                     = true
  enforceRefrelLinks      = true

  [params.taxonomies]
    [params.taxonomies.categories]
      icon = "fa-solid fa-table-cells"
    [params.taxonomies.tags]
      icon = "fa-solid fa-tag"

What is missing in the project?

[bug]: left sidebar with open menu on mobile version sliding down, showing all submenus. On linux, firefox, brave browser mouse scrolling doesn't work. The access to full menu is available through keyboard.

Solution?

No response

What is missing in the theme?

This feature is missing from the theme:

Manage charts within shadocs.

I already have an idea of the implementation:

• check which library should be used to manage charts
• create a shortcode to use and display charts
• enhance documentation

Any ideas what could be causing this error and how to resolve it?

Error: Error building site: failed to render pages: render of "page" failed: execute of template failed: template: _default/single.html:1:2: executing "_default/single.html" at <partial "main.html" (dict "root" . "contentTemplate" "theme/content.html")>: error calling partial: execute of template failed: template: partials/main.html:4:4: executing "partials/main.html" at <partial "theme/includes-head.html" .root>: error calling partial: "G:\me\themes\shadocs\layouts\partials\theme\includes-head.html:21:10": execute of template failed: template: partials/theme/includes-head.html:21:10: executing "partials/theme/includes-head.html" at <.>: range can't iterate over css/shortcuts.css

Table styling defined in assets/sass/theme/global.sass interferes with charts rendered by some standard charting tools like highcharts. Rather than impose specific table styling on all tables, might it be better to just apply it to a class, such as .shadocs-table? I guess this approach would require adding that class to each table in the current shadocs documentation, but it seems this would allow for more generic use of the shadocs theme.

Steps that lead to the issue

I have been playing around learning the basics of Hugo/This theme and I am struggling to understand what piece I am missing.

Creating a very basic single page using an examplesite page as reference doesnt seem to be applying markdown for titles and the collapsible sidebar overlaps the text and does not move with the sidebar when expanding/collapsing.

Expected behavior

Text is aligned to the sidebar and moves along with it like within the example site aswell as Title markdown being applied.

Reproducer

x

Solution?

x

This is described in a separate blogdown issue here, but perhaps it's a Shadocs issue?

Plotly plots generated in RMarkdown using the blogdown package are only rendering in Shadocs if the file is named index.Rmd and lives in its own directory, e.g., test/index.Rmd.

Using other themes, plotly plots render properly from anywhere/anything.Rmd.

Any idea what could be causing this?