onweru / compose Goto Github PK
View Code? Open in Web Editor NEWA Hugo theme for documentation sites.
Home Page: https://composedocs.netlify.app
License: MIT License
A Hugo theme for documentation sites.
Home Page: https://composedocs.netlify.app
License: MIT License
Is it possible to create multi-level menus with this theme? If so, how do I need to create it?
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
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
I cant figure out how/where to change the logo
I have checked all the prerequisites below and I'm yet experiencing a problem
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:
compose/layouts/partials/head.html
Line 4 in dec3f94
It should instead be: {{- $iconsPath := "favicons/" }}
Desktop (please complete the following information):
I have checked all the prerequisites below and I'm yet experiencing a problem
Describe the bug
The navigation buttons at the bottom are nice, but they need a bit of tweaking. For example.
Desktop (please complete the following information):
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
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):
I have checked all the prerequisites below and I'm yet experiencing a problem
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.
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" "." "\"" "\\\"" }}",
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
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 .
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:
Lines 150 to 199 in fc71674
Any tips on fixing that?
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 don't see this is available
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):
12.2.1
99.0b5
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
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):
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
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
Several broken links in the README. I'm too lazy right now to fix them all. Forestry, Clarity theme, MIT license, maybe one more.
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:
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
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.
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.
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.
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)
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
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
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
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.
Including multiple words (space separated) in the search box should be treated as a single string, not return results for each word separately.
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.
Search should account for specifying keyword(s) in double or single quotes to ensure literal string matches.
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.
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.
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.
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
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:
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
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.
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.
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
Describe the bug
When experiencing a 404, the site will send the relevant page however it contains the following
Yback home
back home
If this is the intended spelling / use-case please advise or close this :)
Source for issue can be found here
I have checked all the prerequisites below and I'm yet experiencing a problem
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?
Originally posted by mkovnick January 31, 2022
Hi, I am new to hugo, so forgive the question is it may be simple. I noticed that I get the side menu for any file I put in the "Docs" folder, but not in other folders. I am trying to also make a "Tutorials" folder that would also have a side menu and I cannot figure out how to do it. Hoping for help :-)
I have checked all the prerequisites below and I'm yet experiencing a problem
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
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?
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
12.2.1
99.0b5
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
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
Describe the bug
Navigating to heading anchors doesn't work.
Repro
Desktop (please complete the following information):
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
I have checked all the prerequisites below and I'm yet experiencing a problem
Describe the bug
Mobile sidebar menu is broken on Firefox mobile
Phone:
I have checked all the prerequisites below and I'm yet experiencing a problem
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):
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 don't see this is available
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:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.