thegeeklab / hugo-geekdoc Goto Github PK
View Code? Open in Web Editor NEWHugo theme made for documentation
Home Page: https://geekdocs.de
License: MIT License
Hugo theme made for documentation
Home Page: https://geekdocs.de
License: MIT License
First, congratulations for the theme, really great and well documented !!
I'm trying to move my site to this theme and I've an issue with code hightligh just using the example:
```Shell echo "Hello world" ```
is not displayed nicely but like this:
For "some reasons", the generated hteml is adding some inline CSS
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-Shell" data-lang="Shell"><span style="color:#75715e"># some code</span> echo <span style="color:#e6db74">"Hello world"</span> </code></pre></div>
Not sure if the issue is with the theme or with Hugo highlight... Perhaps also a "navigator issue"...
Thanks in advance
Hi, the file layouts/partials/menu.html
, Can you replace Navigation
and More
with variable?
For example:
replace Navigation
{{ if .Site.Params.Navigation }}
<h2>{{ .Site.Params.Navigation }}</h2>
{{ else }}
<h2>Navigation</h2>
{{ end }}
replace More
{{ if .Site.Params.More }}
<h2>{{ .Site.Params.More }}</h2>
{{ else }}
<h2>More</h2>
{{ end }}
This may facilitate the localization.
Can anybody suggest how to create a netlify.toml file to publish my website in this template?
Thank you
Any possibility of supporting dark mode? Only one other documentation theme listed on the Hugo site supports it right now, but I much prefer the look and features of Geekdoc.
Hugo does try to pluralize folder titles by default. For actual pages this is no problem with the title defined in the frontmatter but for folders it's rather annoying to get something like "Securities" or "Hardwares" instead of just "Security" or "Hardware". Therefore I would suggest to add pluralizelisttitles = false
as a default for the recommended config in the docs.
Any h1
elements within the article.gdoc-markdown
elements gets font-size: 2em
from h1
and line-height: 1.6em
from .gdoc-markdown
(both in main.css). If the title is long enough (and/or screen is small enough) to wrap around this makes the text render on top of itself.
Suggestion: add to main.css
.gdoc-markdown h1 {
line-height: 2rem
}
In firefox (85.0.1 (64-bit) for Ubuntu) pages with images gets truncated.
Steps to reproduce:
I'm not sure what causes this. Rendering the print version directly in firefox works fine, it is only the print that doesn't work. I "solved" this on my site by hiding the footer and adding body{overflow-x: visible}
in the print css.
This may very well be a firefox bug rather than a geekdoc one.
I would like to please request a feature to be able to collapse long code blocks vertically, similarly to how long lines get a scroll bar.
A global variable that defines maximum code block length would suffice.
Ability to override default code block length on an individual basis would be a luxury.
hugo reports the error:
hugo server -D
ERROR 2021/01/08 13:57:25 Failed to read Git log: fatal: twoja obecna gałąź „master” nie ma jeszcze żadnych zapisów
ERROR 2021/01/08 13:57:25 render of "page" failed: execute of template failed: template: _default/single.html:5:7: executing "_default/single.html" at <partial "head" .>: error calling partial: "/home/noiro/Projekty/Hugo projekty/test/themes/hugo-geekdoc/layouts/partials/head.html:18:29": execute of template failed: template: partials/head.html:18:29: executing "partials/head.html" at <index .Site.Data.assets "main.min.css">: error calling index: index of untyped nil
ERROR 2021/01/08 13:57:25 render of "page" failed: execute of template failed: template: _default/single.html:5:7: executing "_default/single.html" at <partial "head" .>: error calling partial: "/home/noiro/Projekty/Hugo projekty/test/themes/hugo-geekdoc/layouts/partials/head.html:18:29": execute of template failed: template: partials/head.html:18:29: executing "partials/head.html" at <index .Site.Data.assets "main.min.css">: error calling index: index of untyped nil
ERROR 2021/01/08 13:57:25 render of "page" failed: execute of template failed: template: _default/single.html:5:7: executing "_default/single.html" at <partial "head" .>: error calling partial: "/home/noiro/Projekty/Hugo projekty/test/themes/hugo-geekdoc/layouts/partials/head.html:18:29": execute of template failed: template: partials/head.html:18:29: executing "partials/head.html" at <index .Site.Data.assets "main.min.css">: error calling index: index of untyped nil
ERROR 2021/01/08 13:57:25 render of "page" failed: execute of template failed: template: posts/single.html:5:7: executing "posts/single.html" at <partial "head" .>: error calling partial: "/home/noiro/Projekty/Hugo projekty/test/themes/hugo-geekdoc/layouts/partials/head.html:18:29": execute of template failed: template: partials/head.html:18:29: executing "partials/head.html" at <index .Site.Data.assets "main.min.css">: error calling index: index of untyped nil
Built in 102 ms
Error: Error building site: failed to render pages: render of "page" failed: execute of template failed: template: _default/single.html:5:7: executing "_default/single.html" at <partial "head" .>: error calling partial: "/home/noiro/Projekty/Hugo projekty/test/themes/hugo-geekdoc/layouts/partials/head.html:18:29": execute of template failed: template: partials/head.html:18:29: executing "partials/head.html" at <index .Site.Data.assets "main.min.css">: error calling index: index of untyped nil
noiro@debian:~/Projekty/Hugo projekty/test$
the page does not have any content yet
theme added as submodule
git submodule add https://github.com/thegeeklab/hugo-geekdoc themes/hugo-geekdoc
We have some documentation sites that have parts in capital letters in their title. For example the shortcut OSPF or BGP. It looks like there is an automation that adds a whitespace after every capital letter and this breaks these titles. I would suggest to limit this behavior to some delimiters like - and _ or make it configurable.
Background:
In my setup parts of the page is set up behind authentication while the search isn't. The search itself then becomes a security issue as the search-data file contains most of the information of those secured pages if they are included in the search.
Proposed solution:
Add the ability to add a page variable (geekdocSkipSearch: true?) marking the page as being ignored by search.
Change line 2 in themes/geekdoc/assets/search-data.json to
{{ range $index, $page := (where .Site.Pages "Params.geekdocSkipSearch" "!=" true) }}
If I have an image in the same directory as the markdown file it is no longer possible to reference it by ![alt](image.png)
. It will render <img src="/image.png" alt="alt">
rather than <img src="image.png" alt="alt">
(adding a preceding /
)
I think removing relURL
in layouts/_default/_markup/render-image.html will fix it (but I don't know what else might break)
When building a site with this template using the --minify
option, some spaces are removed, which is especially noticeable in the breadcrumb at the top of the page. I wonder if this could be worked around somehow?
I am having difficulty putting together the information regarding Taxonomy and Front Matter in ordering my menu item by e.g. date or weight
I have the following layout. Where do I place the weigh/date information so that I can sort my release notes in reverse chronological order i.e. 1.5.2 is the first item
Hi,
I was trying to use this theme as static html's without a web server and all works fine except the search function.
I used the example site and when the search box is clicked, the browser try to load 2 js, but it doesn't work because the path is not relative to the html file.
I tried to put a fixed value in order to see how does it works, and I saw that also the results of the research have the path problem.
Are possible to make the search works also for static html without web server?
While here, I cannot help but notice that Geekdocs requires content/posts
but Geekdoc requires content/post
.
Making them match would be nice :)
Hello,
I have tried to use bitbucket
icon in the data\menu\more.yaml
file to reference on source code located at BitBucket, but it seems that this icon is not present in this theme. Could you please add it?
tldr: Please change delivery of search-data to be .json rather than .js to avoid leaking content data from sites with authentication.
The search result data is generated as a .js file which is excempted (sort of) from CORS rules. This means that if anyone authenticated on a geekdoc-site (alice.doc) visits another site that is nefarious (eve.evil). That site can add alice.doc/js/search-data.js as a javascript resource. While eve.evil can't directly read the javascript, it can access the datastructures the javascript created.
I'll go ahead and report a similar issue with flexsearch
https://geekdocs.de/usage/menus/#file-tree-menu
This says that single files are not supported, yet the example file tree shows two single files, level-2-1.md
and level-2-2.md
which do show up in the menu.
Is this a mistake?
Hello,
Deploying my site on Netlify raises the error :
Error: "/opt/build/repo/themes/hugo-geekdoc/layouts/partials/title.html:11:1": parse failed: template: partials/title.html:11: function "return" not defined
I am using hugo v0.72.0
and hugo-geekdoc : v0.8.3
Have you any idea of what happens and how to fix the problem ?
Thanks for your help.
Your exampleSite uses menu-filetree's partial.
Is there an example of using "menu-bundle" with a data/menu/main.yaml
somewhere ?
I have tried to use same syntax than data/menu/more.yaml
returns a [en] REF_NOT_FOUND: Ref "/docs/Exercice2.1.md" from page "k9s.md": page not found
Thank you !
i downloaded the latest version .. put it in a folder main/themes/geekdoc
i started my main project with hugo server -D
added the geekdocCollapseSection: true
but nothing appears
Hello. Thank you very much for making a great Hugo theme.
I tried to customize the favicon in this theme, but just copying and changing favicons.html
didn't work. Then I checked with Chrome Devtool and noticed that the link to the icon in the head tag was declared twice.
Here is a link to the page where the link to the icon is listed.
https://github.com/thegeeklab/hugo-geekdoc/blob/main/layouts/partials/head/favicons.html#L1
https://github.com/thegeeklab/hugo-geekdoc/blob/main/layouts/partials/head/others.html#L1
This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.
Warning
These dependencies are deprecated:
Datasource | Name | Replacement PR? |
---|---|---|
npm | @eloquent/git-version-webpack-plugin |
These updates are awaiting their schedule. Click on a checkbox to get an update now.
These updates have all been created already. Click a checkbox below to force a retry/rebase of any.
package.json
@cfworker/json-schema 1.12.8
clipboard 2.0.11
flexsearch 0.7.43
katex 0.16.11
lodash 4.17.21
mermaid 10.9.1
store2 2.14.3
uuid 10.0.0
@babel/eslint-parser 7.25.1
@eloquent/git-version-webpack-plugin 5.0.1
autoprefixer 10.4.20
copy-webpack-plugin 12.0.2
css-loader 7.1.2
eslint 8.57.0
eslint-config-prettier 9.1.0
eslint-plugin-prettier 5.2.1
favicons 7.2.0
favicons-webpack-plugin 6.0.1
html-validate 8.21.0
npm-run-all2 6.2.2
postcss-loader 8.1.1
prettier 3.3.3
sass 1.77.8
sass-loader 16.0.0
shx 0.3.4
svg-sprite 2.0.4
svgtofont 5.0.2
webpack 5.93.0
webpack-cli 5.1.4
webpack-manifest-plugin 5.0.0
webpack-remove-empty-scripts 1.0.4
node >=18 <=20
colors 1.4.0
.woodpecker/build-package.yml
.woodpecker/docs.yml
quay.io/thegeeklab/hugo 0.127.0
.woodpecker/notify.yml
.woodpecker/test.yml
quay.io/thegeeklab/hugo 0.127.0
quay.io/thegeeklab/lhci 0.13
Background
When indexing my site with Bing it told me that the descriptions for my pages were too short on almost every page.
Proposed solution:
Change themes/geekdoc/layouts/partials/head.html to use .Description
with partial "title" .
as falback (there is probably a more elegant way to this but...):
<meta name="description" content="{{ if .Description }}{{ .Description }}{{ else }}{{ partial "title" . }}{{ end }}">
Hi,
really like your theme, but the search result links are not working in Safari. Am I missing something?
Anyhow, thanks for your effort.
There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.
Error type: undefined. Note: this is a nested preset so please contact the preset author if you are unable to fix it yourself.
no links are generated in the hint environment
https://ibb.co/9vCGpny
the same link displays correctly outside of the hint environment
First of all, thank you for the nice and clean theme.
I have a clarification question: In the more.yml file I can specify Icons for each list entry. However, how are the icons identified? Which keywords are available to use?
In general: Which Icons (also FontAwesome?) are available and how can I use them in the posts?
Sorry, I checked the documentation, but couldn't find it.
Currently the search does not work against sections which might be surprising for some users.
Should this be added to the theme?
adding:
{{ range $index, $page := union .Site.Pages .Site.Sections }}
to search-data.js allows sections to be indexed and searchable.
When use static files (images) inside Expand shortcode, complete path is to this file is incorrect
{{< expand "Spoiler" >}}
![1](dirInStatic/1.jpg) <-- not working
{{< /expand >}}
![1](dirInStatic/1.jpg) <-- working
I have set geekdocMenuBundle
to true
in my site configuration, and added
geekdocCollapseSection = true
to the topmatter of one of my _index.md
files.
The menu is not collapsible, but when I go back to a file-tree menu it is. Any ideas?
I am using Hugo with GitLab
I am also running python code coverage and sphinx documentation generation.
What is the recommended way to include/reference such data as they are already in HTML format?
Hi, I was thinking about an improvement to the search. When we're searching for a term which is used in different parts of docs, we currently do not recognise where is it coming from. It can become really hard to navigate then - see following example.
I hoped we could get some improvement like this:
This would also turn the search results into a dropdown which I think could be a nice addition as well. It would not push the content of navigation then creating this "jump" and could be dismissed by simply clicking on the screen instead of having to delete the search query.
Let me pls know @xoxys if this is something you'd be interested in bringing to this already awesome theme. I'd be happy to even take care of coding this.
Hugo 0.60 uses Goldmark as its default markdown library, and defines a TableOfContents page variable. This makes the Geekdoc ToC fail ... can you create a different page var (maybe TableOfContents_Geekdoc) and provide a shortcode with if-else that allows both ToCs to be used ?
Thanks.
This is probably a basic question... but why do the posts end up on the news page (rather than any other page)?
There does not appear to be anything in the pages/_index.md
that would signify for the posts to be summarised on that page over any other.
Is it possible to move the news items to be summarised, say, after everything else on the homepage?
Search doesn't appear to work and gives a console error (below).
Browser details:
https://www.whatsmybrowser.org/b/9XT1H
Tested on the getting started site.
Images load but the template is off as shown in this screenshot (that's 100% zoom, didn't zoom in). I believe the style files are not loading correctly.
Firefox 80.0 (64-bit)'s inspection shows one error: "the resource from “http://localhost:1313/main.min.css” was blocked due to MIME type (“text/plain”) mismatch (X-Content-Type-Options: nosniff)."
I don't seem to find any such "main.min.css" file within the website directory:
$ find ./ | grep ".css"
./themes/geekdoc/static/custom.css
./themes/geekdoc/exampleSite/static/custom.css.example
./themes/geekdoc/src/sass/_defaults.scss
./themes/geekdoc/src/sass/_fonts.scss
./themes/geekdoc/src/sass/_print.scss
./themes/geekdoc/src/sass/_shortcodes.scss
./themes/geekdoc/src/sass/main.scss
./themes/geekdoc/src/sass/_base.scss
./themes/geekdoc/src/sass/_markdown.scss
./themes/geekdoc/src/sass/_utils.scss
./themes/geekdoc/src/sass/_normalize.css
./themes/geekdoc/src/sass/_chroma_github.scss
./themes/book/static/katex/katex.min.css
./themes/book/exampleSite/assets/_custom.scss
./themes/book/exampleSite/assets/_variables.scss
./themes/book/exampleSite/resources/_gen/assets/scss
./themes/book/exampleSite/resources/_gen/assets/scss/book.scss_50fc8c04e12a2f59027287995557ceff.json
./themes/book/exampleSite/resources/_gen/assets/scss/book.scss_50fc8c04e12a2f59027287995557ceff.content
./themes/book/exampleSite/resources/_gen/assets/scss/example
./themes/book/exampleSite/resources/_gen/assets/scss/example/book.scss_50fc8c04e12a2f59027287995557ceff.json
./themes/book/exampleSite/resources/_gen/assets/scss/example/book.scss_50fc8c04e12a2f59027287995557ceff.content
./themes/book/assets/_defaults.scss
./themes/book/assets/_custom.scss
./themes/book/assets/_fonts.scss
./themes/book/assets/_print.scss
./themes/book/assets/_shortcodes.scss
./themes/book/assets/_main.scss
./themes/book/assets/_variables.scss
./themes/book/assets/normalize.css
./themes/book/assets/plugins/_numbered.scss
./themes/book/assets/plugins/_scrollbars.scss
./themes/book/assets/plugins/_dark.scss
./themes/book/assets/book.scss
./themes/book/assets/_markdown.scss
./themes/book/assets/_utils.scss
./resources/_gen/assets/scss
./resources/_gen/assets/scss/book.scss_50fc8c04e12a2f59027287995557ceff.json
./resources/_gen/assets/scss/book.scss_50fc8c04e12a2f59027287995557ceff.content
The hugo executable does not print any error on load up:
[enitex@xeon notebook]$ hugo server --minify --theme geekdoc -D
| EN
-------------------+-----
Pages | 11
Paginator pages | 0
Non-page files | 0
Static files | 20
Processed images | 0
Aliases | 1
Sitemaps | 1
Cleaned | 0
Built in 36 ms
Watching for changes in /home/enitex/research/notebook/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /home/enitex/research/notebook/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
To replicate the error:
cd /tmp
hugo new site mytempsite
cd mytempsite
git init
git submodule add https://github.com/xoxys/hugo-geekdoc.git themes/geekdoc
hugo server --theme geekdoc -D
Hello,
I am using hugo service with this theme with base url containing slashes like www.domain.com/base
. And now I see an error in the developer console:
[HTTP/1.1 404 Not Found 93ms] GET https://domain.com/js/flexsearch-ad47a5e1ee.min.js
[HTTP/1.1 404 Not Found 49ms] GET https://domain.com/js/en.search-data.min.3f6252c4c9a592e70d3e2505bff277a3937d744ae3d90318ef06794865625de7.js
[HTTP/1.1 404 Not Found 55ms] GET https://domain.com/js/groupBy-62b30ac391.min.js
As you can see there is no /base
inside URLs listed above. I have set some config variables for hugo to make all links absolute and everything works fine except search:
relativeURLs: false
canonifyURLs: true
I have a question about how to remove the left hand menu in certain pages
My API docs are in OpenAPI.
I have used redo-cli bundle
to create HTML (and sed
to add the front matter)
However the OpeAPI content is very wide (3 columns) and it would be very useful to switch off the left hand nav menu on this one page.
Is there some cleaver shortcode or front matter content I can use to switch this off please?
BTW, the issue is the same if you use Swagger
Originally posted by @alecthegeek in #122
I'm not sure that this is really a bug, perhaps its just not possible, but is there anyway to be able to use tabbing and hints from geekdown within an included file?
When I use:
{{< include file="static/includes/file.md.part" markdown="true" >}}
It gets rendered as markdown and none of geekdocs shortcodes get processed. Is there a way I can edit one of the config files or tweak something else so that shortcodes will work? Single location sourcing is super helpful and I'd like to be able to use it as effectively as possible.
Building with hugo --minify
combines the lines in this span element so there is no space between 'and' and the heart:
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.