onweru / compose Goto Github PK

There is a shadow effect around the "search the docs" when the website is used in light mode. But when used in a dark mode, there is no "visible" shadow effect.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the feature

It be really nice if this theme would either by default or through some configuration parameter be able to consume more screen width which is fairly standard with many other such documentation themes. This is particularly helpful when viewing tables so they appear less squashed.

Desktop (please complete the following information):

• OS: Literally all of them
• Browser: Also all

Is it possible to create multi-level menus with this theme? If so, how do I need to create it?

I don't known how to configure syntax highlighting in compose theme, could you help me?

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug
While changing noClasses=true in config.toml file. the site cannot be change to light mode. It stuck at dark mode.

Desktop (please complete the following information):

• chrome 88

When we click on an element of the left side menu , the scroll brings it (approximately) to the content, sometimes at the wrong section.

For example, that link should bring to the video section, but it bring it to the middle of the content:

I think the correct behaviour would be to bring it exactly to the heading title?

AFAIK this theme has some roots on clarity and some content is copied to the exampleSite for reference, but the blogging feature as described does not work

Looking through the partials of this theme I noticed that all the archive/blog post lists related features were removed. Is there any chance to add it back? if not please remove the related misleading content from the documentation/exampleSite ?

I am open to contributing if necessary, and most probably will just copy the functionality back from clarity

Talking about clarity, is there any plan to add back its code features? I can open another issue to track this one, if needed.

The default logo is approx 160x35 and the page layout works. However, if a taller logo is used (160x70) the first line of text (approx h1's worth) becomes hidden behind the now taller header. This seems to be the case on MS Edge and on Firefox. I've not tested on others.

I believe a taller header should push the main body down - not overlap it.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the feature

In the Compose theme today, pages are globally weighed to determine ordering in the left-hand navigation pane. This approach makes it quite difficult when adding or extending pages as when a site grows organically. What I suggest as a better approach is to have the pages weighed relative to the sections in which they're located.

For example, in a site composed like this (under /content/docs/)

$ tree .
.
├── _index.md
├── about
│   ├── architecture.md
│   ├── features.md
│   └── roadmap.md
├── installation
│   ├── _index.md
│   ├── daemonset.md
│   ├── flags.md
│   └── static.md
└── usage
    ├── _index.md
    ├── cloud-provider.md
    ├── equinix.md
    ├── k3s.md
    └── kind.md

The pages under /about should be weighed only in relation to other pages in /about and not pages in either /installation or /usage. This will probably require that there be another control somewhere in the theme to specify the ordering of those page categories. The ideal location would probably be in the menu.toml file. Once that's done, the subpages can be weighed relative to each other.

Desktop (please complete the following information):

• OS: N/A
• Browser: N/A

I cant figure out how/where to change the logo

Hello @onweru

In the latest update I noticed that sidebars links open in new tabs. However this is not good from a UX standpoint.

Please remove the attribute target="_blank" from internal links.

Hi!

I'm facing an issue when I have a lot of elements in the left sidebar.
When scrolling down, the "right part", where there is the content is, needs to be totally at the bottom before the left menu is scrollable .

Here how it looks like:

I believe a better experience would be if we can scroll down on the menu independently of the content on the right?

I've tried to dig in, I believe it happen in the customizeSidebar function:

Any tips on fixing that?

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the feature

The nav bar on the left-hand side is nice, but for some page content (like tables) you could really use the extra screen width. It'd be helpful if users could optionally collapse that side bar on the left and have the content on the page re-flow across that additional space.

Desktop (please complete the following information):

• OS: Mac 10.16.4
• Browser: Firefox 93

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

As the length of a page name increases, the next/previous arrow icons for that page shrink. They also change height, with the previous page arrow going downward and the next page arrow going upward.

This can be observed on the live example site.

Desktop (please complete the following information):

• OS: macOS 12.2.1
• Browser: Firefox 99.0b5

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Very minor, but when clicking anchor links on page headings at any level, the site shows "Link Copied" for everyone clicked. Correct behavior should be this is either shown and then hidden, or the last link to be clicked displays this since the clipboard buffer will only hold the last one.

Desktop (please complete the following information):

• OS: Mac 10.14.6
• Browser: Firefox 93

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

When I try to use mermaid, it only works if the string "mermaid" is in the document outside of tags.

+++
title="Mermaid Test"
+++ 

mermaid
{{< mermaid >}}
pie
  title Key elements in Product X
  "Calcium" : 42.96
  "Potassium" : 50.05
  "Magnesium" : 10.01
  "Iron" :  5
{{< /mermaid >}}

The above works.

+++
title="Mermaid Test"
+++ 

{{< mermaid >}}
pie
  title Key elements in Product X
  "Calcium" : 42.96
  "Potassium" : 50.05
  "Magnesium" : 10.01
  "Iron" :  5
{{< /mermaid >}}

The above doesn't work, and just renders the following text under the title:

pie title Key elements in Product X "Calcium" : 42.96 "Potassium" : 50.05 "Magnesium" : 10.01 "Iron" : 5

I can put the string "mermaid" anywhere and it works, but it doesn't seem this is intentional.

Desktop (please complete the following information):

• OS: Windows 10
• Browser: Microsoft Edge Version 91.0.864.37 (Official build) (64-bit)

In order to display the page correctly, when visiting an anchor link, negative margin including a positiv padding must be added to the stylesheet for the link_owner class in order to skip the header of the page.

Example:

margin-top: -80px;
padding-top: 90px;

This example will add a distance delta of 10px above the heading element. This will have an impact on the distance of the heading element to the header element when visiting the page using an anchor link as well as distances between headings and other siblings.

You will be able to actually see the heading this way. Currently it is behind the header of the page.
Example link: https://themes.gohugo.io//theme/compose/docs/getting-started/shortcodes/#column

In a page with a long list of page links (ex., /docs/getting-started/dummy-content/), any links that appear in the gradiant zone towards the bottom are not clickable, however those above it are. This would likely vary depending on the resolution of the user's browser.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the feature request

The left-side nav bar is very nice, but the only down side is it flattens all markdown headings to appear as though they're on the same "level". This makes it challenging when adopting this theme coming from other Markdown content where there has been some care taken to ensure headings have structure defining the content. It'd be nice if there was some simple way of reflecting maybe two or three levels of this structure. Alternatively, multiple pages would need to be created to keep this visually distinct.

Desktop (please complete the following information):

• OS: Mac 10.14.6
• Browser: Firefox 93

First of all, thank you so much @onweru for creating this amazing theme! I am wondering whether it's possible to change the font-size and family. My original thought is that it should be relatively easy, so I tried to edit font-size within body of assets/sass/_base.sass. However, the font and font-size do not change. May I ask where I can make the changes? Thank you so much again, for your time and efforts!

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

All branding assets for this theme related to images need to be stored together without having some components coming from the theme while others come from site directories. The thing missing here is favicons, which still are configured to point to the theme directory. Change these so that they can be picked up from /static/images just like the banner images.

Desktop (please complete the following information):

• OS: N/A
• Browser: N/A

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

If you set a baseURL in a subdirectory of a website/domain (e.g. http://www.example.com/somedirectory), favicons are not loaded properly. This is due to the leading / in this line of code:

It should instead be: {{- $iconsPath := "favicons/" }}

Desktop (please complete the following information):

• OS: Windows 10
• Browser: Firefox, Chrome

This issue will serve as a general post for aggregation of all fixes and suggested improvements to the search function within the Compose theme. It will be updated over time.

Fixes

1. After entering and then removing search terms from the search box, the results drop-down does not clear which obstructs the page and can only be removed by either refreshing or navigating away. Example (at 0:27)

2. When entering a search term for which at least one match is known, then removing that term and typing a new one for which there are no known matches returns all possible pages even though this is false. This represents different behavior than when the page is clean and then searching for the same term (again, for which there are no matches). The search function appears to stop evaluating the search box input after >0 matches are found. Example

3. Similar to the above, when entering a search term for which there are known matches, pausing while typing, then continuing to add characters to the end of that word does not eliminate any results. This gives the false impression that the word typed has matches on pages. Example

4. Searches that include only integers appear to be either broken or returning results invisible to the user. A search that contains an exact match appears to return the correct results, however, but it's unclear where this breaks down. Example

Improvements

1. When clicking a search result after entering a keyword, the page returned could be very long and is not clear where that keyword is located. It would be helpful for there to be some better visual/UX "pointer" to show the user where specifically that term is located, or if multiple on a given page handling for multiple results.

2. Including multiple words (space separated) in the search box should be treated as a single string, not return results for each word separately.

3. This search functionality does not have the capability to enter a term and hit "enter" which then presents a separate page with the findings of the search. This lack of behavior makes searching a bit difficult to initially understand. Not sure how it could be implemented, but a more "traditional" approach as a response to this behavior might be better.

4. Search should account for specifying keyword(s) in double or single quotes to ensure literal string matches.

5. Search appears to view the entire site as its domain. There should be a parameter which limits the field of vision of the search indexing to exclude, as an example, the home page if desired. Presently, searching for something like "GitHub" which appears only on the home page, is returned by search.

6. Search should allow for finding substrings. For example, on the home page is the string "forestry.io" which appears nowhere else. This is only returned if the user types "forestry.io" exactly as it appears. While wildcard globbing seems to work (searching for "forestry*" returns the result), you might want to allow for substring match without it.

7. It would be super great to be able to constrain where matches should be returned. For example, a user might choose to search only for terms found within a code block versus other text. Or a user might choose to only search within notes.

8. Similar to the above feature, a user may wish to constrain a search to a page (with children) on which focus is currently set rather than performing the search globally. May want to investigate some ability to detect the current page and offer to perform the search on that page and down (traverse links) or something similar.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

The Docs Menu element seems to be slightly too large for the container it resides in on a mobile device, so there are scroll bars visible both horizontally and vertically in this view. This make the page look a bit unpolished, but I'm guessing it's also pretty simple to fix.

See the image below with the scroll bars marked in red.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug
On this page, you can toggle the light/dark mode and navigate around with that mode staying in effect. But upon navigating to Equinix Metal page under the "Usage" category, something in the JS breaks and the page is forced into dark mode (if it was previously in light). The toggle button flips and can't be clicked. So it "broke" somehow.

Desktop (please complete the following information):

• OS: Mac 10.14.6
• Browser: Firefox 93

Is there any way I can have a clickable link like this, inside a table value?

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Navigating to heading anchors doesn't work.

Repro

• Navigate to the documentation/example site: https://docs.neuralvibes.com/docs/compose
• Click on any anchor link by a heading to copy it, for example: https://docs.neuralvibes.com/docs/compose/install-theme/#option-3-great-for-testing-quickly
• paste link into chrome address bar & hit enter
• Correct page is loaded, but the location is the top of the page, not the anchor.

Desktop (please complete the following information):

• OS: windows 10
• Browser chrome 89

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Mobile sidebar menu is broken on Firefox mobile

Phone:

• OS: Android 10
• Browser: Firefox 85.1

Screenshoots

I have checked all the prerequisites below and I'm yet experiencing a problem

• [o] Read the README.md
• [o] Have the extended version of Hugo installed
• [o] Used the example site's config .toml as a reference

after guide with the readme doc, run the code

"git clone --recurse-submodules --depth 1 https://github.com/onweru/compose.git
cd compose/exampleSite/
hugo server --themesDir ../.."

then I open the http://127.0.0.1:1313/ page which shows the wrong layout, seems not to load the CSS corectlly. I try to make it on mac look work but failed on windows. How to solve this problem?

• OS: [Windows 10]
• Browser [chrome 88.0.4324.182]

I want to configure the --theme variable in _variables.sass.
The problem is that the sass file isn't evaluated by hugo so it's not that easy for me with my current knowledge of hugo to do it by myself.
If somebody can point me in the right direction I can do it by myself.
I would be glad if this gets implemented soon because currently I have a second git branch just to change the color.

Thank you very much

Similar to #49, the icons for code blocks are assumed to be in the root and when using an alternate baseURL they do not work but also seem to corrupt most of the page. Chrome console:

This is mostly a feature request.

I believe the "top menu bar" does not need to be visible when you start scrolling the content it is taking a good amount of space, especially on small devices.

In https://github.com/onweru/compose#examplesite the user guide link is broken. Hope you're well :)

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

When fenced code blocks are used without a language, they display (and cause the tool palette buttons to be displayed) differently which causes some collisions.

vs

Desktop (please complete the following information):

• OS: Mac 10.14.6
• Browser: Firefox 93.0

I have checked all the prerequisites below and I don't see this is available

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the feature

Looks like custom SASS is a supported feature on Clarity. In the Compose docs, this section is empty.

Desktop (please complete the following information):

• OS: macOS 12.2.1
• Browser: Firefox 99.0b5

When narrowing the demo page or viewing it on a Mobile device, the nav items appear to collapse under a single "Menu" item, though the individual nav items (e.g. Docs, Example, GitHub) are inaccessible.

I tried toying with nav.html and _nav.css, but I'm swinging a hammer blindly.

In any case, I love the theme, asante sana

Narrow/Mobile (collapsed "Menu"):

Where did the nav items go? Off-screen to the left?

I have checked all the prerequisites below and I don't see this is available

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the feature

I just set up a site with Compose, and immediately got a reaction from users asking "why are there two menus on top of eachother on the page on mobile? I didn't think about this myself while setting it up, but now that it's brought to my attention it is quite odd.

This request is for adding an option for, or updating the theme in general to merge the two menus into one menu with sections. I imagine that when you open the top menu (which would be the only one after implementing this change), it would first list the top bar navigation links, and then have a separator saying Docs Menu for the default setup, after which the Docs links would be listed.

In short the two menus are strange, and take up a lot of real estate at the top of the view on mobile.

Something like this from top to bottom is what I imagine, the = is to emphasize a section separator:

Search the docs
Tutorials
Example
=== Docs Menu ===
Themes' Docs
Compose Docs
Install theme
...

Image highlighting the two menus stacked on top of each other:

Discussed in #72

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Compose already creates buttons by default to the next and previous page:

It would be nice if such a button would be created from the index of a page to the first of its subpages automatically.

Your example site does this manually:

This has the following drawbacks:

1. It must be done manually while it could be done automatically
2. It looks different as the arrow is missing
3. It positioned at the left while the default navigation buttons to go "forward" are positioned at the right.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Locally running hugo server and http://localhost:1313/workflows/ everything runs great though I get 404's for a number of the SVG's like carly.svg and others.

After building and publishing to github pages things get really wonky appearance wise.

I am hosting via github pages and thus end up with a subdirectory as my baseURL

https://erzz.github.io/workflows/

At first almost all images, favicons etc were missing until I added the following to config.toml

RelativeURLs=true
CanonifyURLs=true

That fixed a lot - but when you then navigate to docs things start to get messy with layout. e.g. https://erzz.github.io/workflows/docs/container/container-oidc.yml/

Checking out whats happening on page load then its clear that a bunch of svg's are resulting in 404

My build for the pages is pretty standard fair - see https://github.com/erzz/workflows/blob/main/.github/workflows/docs.yml for details.

Full config looks like:

baseURL = "https://erzz.github.io/workflows"
title = "erzz/workflows"
enableRobotsTXT = true
# this example loads the theme as hugo module
# comment out line below, and uncomment the line after it if you prefer to load the theme normally
theme = ["github.com/onweru/compose"]
#theme = "compose"
enableGitInfo = true

disableKinds = ["taxonomy", "taxonomyTerm"]

RelativeURLs=true
CanonifyURLs=true

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

Desktop (please complete the following information):

• OS: MacOS
• Browser: Tried various

Describe the bug

When experiencing a 404, the site will send the relevant page however it contains the following

• Yback home
  I think it should just be
• back home

If this is the intended spelling / use-case please advise or close this :)

Source for issue can be found here

nohi

The style is broken when the site is not deployed to the root path.

Reproducer:

hugo new site compose-example
cd compose-example
git init
git submodule add --force https://github.com/onweru/compose/ themes/compose
cp -rav themes/compose/exampleSite/* .

After committing and starting hugo server everything works nicely on the code snippets page:

Now try the same with a different baseURL:

HUGO_BASEURL="http://localhost:1313/compose/example" hugo server

And the worst is when you deploy this theme to a sub-folder in a GitLab pages project where it completely breaks the page with the syntax highlighting examples:

This happens on both Firefox and Chromium, not browser related. My OS is Linux (Fedora 34), not sure what GitLab Pages use.

Hugo version I use locally: v0.80.0/extended

Hugo version in GitLab Pages: hugo_extended:latest

My suspicion is that the theme has some / and points to an absolute path under the root for loading some assets, but haven't tracked it down yet.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

The navigation buttons at the bottom are nice, but they need a bit of tweaking. For example.

1. the Search page should not be navigable.
2. when there are multiple high-level structures to the docs (ex., content/docs/foo and content/docs/bar) the navigation buttons shouldn't just look at the global weights across all pages but only look in the same tree as the current page.
3. the page categories/sections should show as the next links in the navigation buttons, not just the "sub-pages".

Desktop (please complete the following information):

• OS: Mac 10.14.6
• Browser: Firefox 93

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the feature

Especially for software projects, companies/communities often need to maintain documentation for separate versions especially as documentation is now fairly standard to store in git. Consider supporting versioning documentation similar to how some other themes do it (for example Docsy).

Desktop (please complete the following information):

• OS: N/A
• Browser: N/A

Several broken links in the README. I'm too lazy right now to fix them all. Forestry, Clarity theme, MIT license, maybe one more.

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Currently, this theme does not support customCSS like clarity. This is a request to add that feature to this theme too.
reference implementation in clarity

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

Describe the bug

Tables on mobile are not displaying correctly depending on columns. If not compressed, the page cannot be scrolled horizontally.

Desktop (please complete the following information):

• OS: Android 11
• Browser: Chrome 96
• Device: Pixel 4a

I have checked all the prerequisites below and I'm yet experiencing a problem

• Read the README.md
• Have the extended version of Hugo installed
• Used the exampleSite's config.toml as a reference

A clear and concise description of what the bug is. [REPLACE]

If I add a top level directory besides the 'docs' section, it does not have a table of contents. Especially I do not want to have a nested structure where 'docs' is the top level. If I rename the top level docs directory, the table of contents disappears.

Desktop (please complete the following information):

• OS: MacOS
• Browser all

The current example site does not work, as there is content including quotes. (")

I was able to fix this by adjusting search.js:

"body": "{{ apply .PlainWords "replace" "." "\"" "\\\"" }}",