🔯 Modern, batteries-included Hugo theme for creating beautiful doc, blog and static websites
Home Page: https://imfing.github.io/hextra/
License: MIT License
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
Currently, the "copy code" buttons are created in advance and included directly in the HTML. This approach has a downside: it adds SVG icons to every code block, which messes up how the RSS feed looks.
hextra/layouts/_default/_markup/render-codeblock.html
Lines 18 to 21 in 2df3c56
A better way to handle this is to shift the "copy code" button creation to the assets/js/code-copy.js file. By doing this, the buttons get added dynamically when the page loads, avoiding any issues with the RSS feed.
Enabling search in site config while using Hexstra theme causes a build error:
Error: error building site: EXECUTE-AS-TEMPLATE: failed to transform "json/search-data.json" (application/json):
template: json/search-data.json:10:15: executing "json/search-data.json" at <partial "utils/fragments" $page>:
error calling partial: ".../imfing/[email protected]/layouts/partials/utils/fragments.html:39:62": execute of template failed:
template: partials/utils/fragments.html:39:62: executing "partials/utils/fragments.html"
at <markdownify>: error calling markdownify: runtime error: slice bounds out of range [:640] with capacity 512
Steps To Reproduce
hugo.yaml and set params.search.enable to true.hugo server --logLevel debug --disableFastRender -p 1313 --noHTTPCache.Environment
Originally posted by saurabh-mish September 12, 2023
A configuration option for full screen mode. It will use the complete width of the screen like this theme for instance.
as giscus support is implemented in #89
we also need to add docs page for how to enable it. besides, put the example config in the exampleSite/hugo.yaml
Hi.
I'm trying to build a knowledge sharing site. I'm testing with about 4000 pages and my machine would crash instantly if I try to search even it's a really fast one. Is there anyway to optimize search speed or config alternative search engine?
Originally posted by LITUATUI October 2, 2023
Support for modern image formats is a great way to improve the speed of a website.
The Hugo Clarity theme has a great way of dealing with new image formats like AVIF, JXL or WebP.
If you reference an image such as sample.jpg in your post, Hugo Clarity will check to see if the same image (based on filename) exists in the modern formats of WebP, AVIF or JXL. If it does, these will be presented to browsers as alternative options. Browsers that can support these formats will load them, while browsers that do not will fall-back to the default image.
This process works for images with the file extensions jpg, jpeg, png, and gif.
Implemented this way would have no disadvantages even for old browsers that don't support modern image formats.
Hugo Bootstrap Theme also implemented this neat feature.
Then we can use ImageMagick to batch convert all JPG and PNG files in our image folder.
magick mogrify -format avif -depth 10 -define heic:speed=2 *.jpg
magick mogrify -format avif -depth 10 -define heic:speed=2 *.png
```</div>
Hi there!
Sorry this may be a rookie question but what path I should use to reference the image for it to be added to my page inside one of the folders? I've tried putting .jpg files to /static/images/ and then referencing as /images/process2.jpg but the image not being added.
I then tried moving images around and referencing different paths but no success so far.
https://github.com/vovavasylyna/landusheva
Best,
Vova
How can I add custom fonts found on Google Fonts? Is it possible to store them somewhere under /static/fonts/FONT_NAME.ttf and then call them out in assets/css/custom.css? If so, how? Or perhaps any other way?
I've tried simply replacing default ones below with Inter font, but it didn't help, unfortunately.
Hi, I'd like to clone this repo and quickly make a few edits for a different project of mine. I am aware of the Hextra Starter Template repo, but I wanna start with this repository instead because there's already content in place and it's easier to edit. However, when I clone this repo and run the following commands:
git clone https://github.com/imfing/hextra.git
cd hextra
hugo mod
# Start the server
hugo mod tidy
hugo server --logLevel debug --disableFastRender -p 1313
I see this output in the browser:
Which is obviously an issue, so I was hoping for a way to fix this. Any ideas?
♥ Cheers, love this theme.
Store images for the README
Clicking the image card on this page, redirects to a page on GitHub, which shows a 404 error.
Since the image is being used from unsplash.com, it should only be displayed as it is and not redirect to GitHub. Clicking it should do nothing.
Hi there,
Thank you for sharing such as nice theme.
However, I have been trying to build and deploy Hextra to a GitHub page all night, but I haven't been able to make it work
I've tried using the Hextra template and also tried building from scratch based on Hextra's instruction, but neither approach worked.
On the local server (http://localhost:1313/) I can view the new site using hugo server --buildDrafts --disableFastRender. I can also successfully use GitHub Actions to build and deploy it. However, every time I click on the site's link, it only displays the repository's name and the contents of the README.md, not the content the site should have.
I'm not sure if I need to convert the site to static with Hugo. But after trying hugo or hugo -D in the terminal and then uploading the files onto the GitHub repo, it still just displays the repository's name and the README.md content after clicking the link of the site.
I'm also not sure if the failure is because Hextra requires special flags like --buildDrafts and --disableFastRender when running hugo server since other themes don't need these flags.
Could you please help me solve this? Or provide guidance on how to correctly deploy a blog with the Hextra theme on GitHub pages? I've been able to deploy other themes based on Hugo to GitHub pages successfully.
On slower internet connections, the diagrams page takes a lot longer to load than other pages.
View the source of any page.
You can see that, in the <head> tag, the value of integrity attribute is missing for external stylesheets (<link /> tags):
For example, on this page I observed that:
<link href="/hextra/css/compiled/main.min.ecc9bbfeacf5a6f4e36c4a8ef28ad870def480b01c4126a5fb3f7fe92c9fb3a3.css" rel=stylesheet integrity>
<link href=/hextra/css/custom.min.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.css rel=stylesheet integrity>
im on windows but the symbol is a mac only symbol
The Logo height and width variables are incorrectly called.
See below:
<img class="block dark:hidden" src="{{ $logoPath | relURL }}" alt="{{ .Site.Title }}" height="{{ $logoWidth }}" width="{{ $logoHeight }}" />
<img class="hidden dark:block" src="{{ $logoDarkPath | relURL }}" alt="{{ .Site.Title }}" height="{{ $logoWidth }}" width="{{ $logoHeight }}" />
Should be changed to:
<img class="block dark:hidden" src="{{ $logoPath | relURL }}" alt="{{ .Site.Title }}" height="{{ $logoHeight}}" width="{{ $logoWidth}}" />
<img class="hidden dark:block" src="{{ $logoDarkPath | relURL }}" alt="{{ .Site.Title }}" height="{{ $logoHeight}}" width="{{ $logoWidth}}" />
Feature request: Configuration option to sort blog post by:
weighttitleHey @imfing
The template is mostly working out great, but there's a small persisting issue of the custom favicons. I tried cloning a fresh starter template and following the instructions we added in PR #37, but I cannot seem to override the default favicons. I created a video to demo this:
In the above video, I have:
static.Let's find a solution to this.
Originally posted by iju707 September 24, 2023
giscus is one of comments system, using github discussions.
https://giscus.app/
The 'Syntax Highlighting' card here leads to 404 page.
On https://imfing.github.io/, each article shows the same last updated date.
Each page should display the last date when the corresponding Markdown file was edited.
A user may want to add a link to the license that's applicable for the site. In this case a modified copyright text in the footer may look like:
© 2023 FirstName LastName - [Some License]("https://www.somelicense.com/version")
The date can be rendered using Hugo template instead of hardcoding
FirstName and LastName can be taken from a field in hugo.yaml
Link for a specific version of a license can be provided
Hi,
I would like to the replace the default h1 header on the index.html with a custom component. Is it possible to make this a partial so it can be overridden?
Thanks!
Tested using the latest version of hugo (extended version) running in docker:
$ hugo version
hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended linux/amd64 BuildDate=2023-03-12T11:40:50Z VendorInfo=hugoguru
Steps to reproduce: just follow the Getting Started instructions:
$ hugo new site my-site --format=yaml
$ cd my-site/
$ hugo mod init github.com/username/my-site
$ hugo mod get github.com/imfing/hextra
$ cat <<EOT >>config.yaml
module:
imports:
- path: github.com/imfing/hextra
EOT
$ hugo new content/_index.md
$ hugo new content/docs/_index.md
$ hugo server --buildDrafts --disableFastRender
The hugo server throws:
Start building sites …
hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended linux/amd64 BuildDate=2023-03-12T11:40:50Z VendorInfo=hugoguru
Error: Error building site: failed to render pages: render of "section" failed: "/tmp/modules/filecache/modules/pkg/mod/github.com/imfing/[email protected]/layouts/section/section.rss.xml:20:17": execute of template failed: template: section/section.rss.xml:20:17: executing "section/section.rss.xml" at <site>: can't evaluate field LanguageCode in type *langs.Language
Built in 43 ms
The config.yaml:
$ cat config.yaml
baseURL: http://example.org/
languageCode: en-us
title: My New Hugo Site
module:
imports:
- path: github.com/imfing/hextra
Personally I would recommend Go modules, but for those who don't know Go or don't want to install Go, submodule may be an alternative solution.
https://www.docsy.dev/docs/get-started/other-options/#option-1-docsy-as-a-git-submodule
The "Blog" heading on this page appears to be in H1, and the "About" heading on this page appears to be H2 and have a additional line break.
This can be noticed when switching between these pages.
If we're using a custom _index.md in the content/ directory, the width of the text is too narrow.
In my opinion it makes sense for this text to span a little wider (10% - 15% more), because there are no navigation menus or either side.
Headings containing apostrophe ' dont rendered correctly under "On this page".
Example:
When using card inside a details or tabs shortcode, the first card will have inconsistent style like this:
This rule is the reason:
.content p:first-child {
margin-top: 0;
}
hextra/layouts/_default/baseof.html
Line 7 in 2df3c56
The left side of the above will be falsy if a user disables footer (enable=false) which will make it default to true...
For features that's default on it's easier to use a disable option, I think.
Great looking theme.
Hugo v0.119.0 introduced a new function Process that is more general
so we don't need the if block in the card.html image processing logic:
https://github.com/imfing/hextra/blob/main/layouts/shortcodes/card.html#L15
Feature request: Tags associated with a post could be displayed above the date when listing all posts.
The current copyright text is:
© 2023 Hextra Project.
Feature request for this text to be configurable.
Originally posted by iju707 September 27, 2023
Having a back-to-top button would be very helpful in long-form content.
I think it would be better if it is located at the bottom right.
Hello, I just started trying to use hugo to write documents. I discovered the Hextra theme, which is very lightweight and even supports Chinese search. I like it very much.
I have some questions. as follows:
How to customize the configuration to hide the navigation at the top of the page or the panel at the footer? Just like the book theme. Or modify the height of the bottom panel. The current default is too high and there is a lot of blank space.
By the way, is it possible to increase the size of the dark mode or light mode icons, they are a bit small now and hard to notice in dark mode.
Thank you so much! English is not my first language. I hope you can understand the results of Google Translate.
Hi,
I have followed the Guide and updated my hugo.yaml file. But I cannot find the API invocation to google analytics.
How to reproduce
cd into exampleSite foldergoogleAnalytics: G-xxxx in the hugo.yaml filehugo server --logLevel debug --disableFastRenderI want to make section bellow.
content
blog is used "blog layout"
but test1, test2 are used "_default layout", but I want to use "docs layout"
and I find a solution, copying docs layout files into layout/test1 or layout/test2.
but if hextra is upgraded, I copy again. It's too cumbersome.
Thank you for this wonderful template. It's really simple to install and edit even for someone like me who doesn't know much about this stuff. I just have a couple questions:
https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options
---
title: Configuration
sidebar:
open: false
---This option only works for _index.md. This option didn't work for other .md files under the same folder to not show them in the sidebar.
and, Is it possible for the documents to fully fit (%100) across the entire page when I hide the sidebar?
Is it possible to 100% fit the whole page for the blog tab only when needed.
Can I edit the home page to automatically show the last 10 or 20 newly added notes? like recently added.
I followed the getting started guide for a new project, but the CSS doesn't render when running hugo server
I even removed the archetypes/default.md, but still unable to render CSS.
Support more shortcodes.
Hope to support more short codes, such as hints, buttons, columns, etc.
I think the usage rate of hints is very high, and I hope it can be supported as soon as possible. Currently I am using callout to make similar styles.
Thank you so much!
Feature Description
I'd like a feature like light-mode-switch: false and/or dark-mode: false to control whether a user can toggle the dark mode and/or to enforce only light mode as default while hiding the mode toggle.
I prefer the site to be seen in light mode and don't want to use dark mode as a default.
Originally posted by thangisme October 2, 2023
With around 4K page, it takes a while to build the site. Which is not the case with other themes.
Template Metrics:
cumulative average maximum cache percent cached total
duration duration duration potential cached count count template
---------- -------- -------- --------- ------- ------ ----- --------
1h11m15.223847094s 1.700566367s 3.723108386s 0 0 0 2514 docs/single.html
29m25.170236303s 566.304214ms 2.228949419s 29 0 0 3117 partials/sidebar.html
17m4.13874766s 1.712606601s 3.15029002s 0 0 0 598 docs/list.html
9m44.776173335s 187.488353ms 1.667255081s 100 0 0 3119 partials/theme-toggle.html
8m26.370114506s 162.715332ms 2.49520532s 52 0 0 3112 partials/breadcrumb.html
29.106906383s 9.338115ms 2.961663767s 84 0 0 3117 partials/scripts.html
18.830250172s 6.050851ms 1.24994449s 12 0 0 3112 partials/components/pager.html
17.525731147s 5.622627ms 1.394370744s 16 0 0 3117 partials/head.html
8.323090391s 2.670224ms 935.323309ms 3 0 0 3117 partials/footer.html
4.253779071s 1.417926357s 1.718321097s 0 0 0 3 _default/list.html
3.254211742s 3.254211742s 3.254211742s 0 0 0 1 _default/single.html
3.125610084s 1.002762ms 302.079788ms 94 0 0 3117 partials/navbar.html
2.958057535s 2.958057535s 2.958057535s 0 0 0 1 js/flexsearch.js
2.772303655s 2.772303655s 2.772303655s 0 0 0 1 json/search-data.json
2.324423135s 84.138µs 10.123734ms 32 0 0 27626 partials/utils/icon.html
1.646970444s 1.646970444s 1.646970444s 0 0 0 1 hextra-home.html
1.108133334s 16.539303ms 743.714675ms 0 0 0 67 shortcodes/card.html
473.390865ms 188.002µs 1.148266ms 0 0 0 2518 partials/utils/fragments.html
408.630441ms 679.917µs 12.980529ms 0 0 0 601 _default/list.rss.xml
328.305514ms 105.361µs 829.74µs 100 0 0 3116 partials/toc.html
325.333061ms 40.666632ms 325.054054ms 0 0 0 8 shortcodes/hextra/feature-card.html
173.680592ms 55.756µs 1.771161ms 100 0 0 3115 partials/components/last-updated.html
171.013371ms 54.864µs 2.740091ms 7 0 0 3117 partials/opengraph.html
140.474137ms 22.533µs 1.019029ms 100 0 0 6234 partials/search.html
140.084677ms 44.942µs 1.298499ms 19 0 0 3117 partials/utils/page-description.html
129.101685ms 41.431µs 3.434975ms 100 0 0 3116 partials/components/comments.html
83.38736ms 26.752µs 1.462905ms 100 0 0 3117 partials/utils/page-width.html
74.589641ms 23.929µs 10.828863ms 100 100 3116 3117 partials/head-css.html
25.315915ms 8.121µs 9.142074ms 100 100 3116 3117 partials/favicons.html
24.946966ms 24.946966ms 24.946966ms 0 0 0 1 _internal/_default/sitemap.xml
21.683486ms 8.625µs 56.337µs 0 0 0 2514 shortcodes/rawhtml.html
4.409197ms 881.839µs 1.228166ms 0 0 0 5 shortcodes/tab.html
1.837825ms 589ns 46.988µs 100 0 0 3117 partials/custom/head-end.html
624.158µs 104.026µs 586.997µs 0 0 0 6 shortcodes/cards.html
385.126µs 192.563µs 364.407µs 100 0 0 2 partials/language-switch.html
251.657µs 251.657µs 251.657µs 0 0 0 1 shortcodes/hextra/feature-grid.html
220.678µs 220.678µs 220.678µs 0 0 0 1 shortcodes/icon.html
162.938µs 81.469µs 143.15µs 0 0 0 2 shortcodes/tabs.html
160.524µs 160.524µs 160.524µs 0 0 0 1 shortcodes/hextra/hero-badge.html
118.484µs 118.484µs 118.484µs 0 0 0 1 shortcodes/hextra/hero-headline.html
113.495µs 113.495µs 113.495µs 0 0 0 1 404.html
| EN
-------------------+-------
Pages | 3719
Paginator pages | 0
Non-page files | 0
Static files | 6726
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 348461 ms
Someone at Hugo forum pointed out :
https://github.com/imfing/hextra/blob/main/layouts/partials/sidebar.html#L66-L95 4
The number of iterations increases quadratically in relation to the number of content pages (i.e., 3000 pages = 90,000,000 iterations).
Could you take a look?
So I am overriding/changing styles of pages eg. ./layouts/blog/list.html (my site's root, NOT inside themes/hextra/layouts) but the new Tailwind style classes are not being reflected on my site.
To clarify: the existing Tailwind classes that comes with the theme are working out-of-the-box - but the classes I am adding are not.
How do I force Tailwind to refresh css so that it includes the styles of the classes?
Looks like the command hugo server does not run alongside with Tailwind watch process? Am I missing something?
Hi,
Great theme. Will you add tag support for docs?
Thanks
I've used the template repository to create a hugo site and the index.xml doesn't generate full contents it only generates summary
Help or insight needed on this !
Enable Full Text RSS feed
this is an example site which generates full content which enhances readability in RSS
https://blog.sahilister.in/index.xml
I've found your theme very suitable for my project documetation. Very convinient to setup, and has a clean look. Great work!
I cannot get a local image to render, on my local server. Any web images works as expected.
These two variants show a broken image placeholder in Chrome. My image is in the same folder as the doc page.
{{< cards >}}
{{< card link="diagram-atlas-db-user-management.png" title="Atlas Database User Management" image="diagram-atlas-db-user-management.png">}}
{{< /cards >}}
This Hugo code is dispaing as a text from my page.
{{ $image := .Resources.GetMatch "diagram-atlas-db-user-management.png" }}
{{ with $image }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}Debugging info, versions
$ go version
go version go1.20.5 linux/amd64
$ hugo version
hugo v0.117.0-b2f0696cad918fb61420a6aff173eb36662b406e+extended linux/amd64 BuildDate=2023-08-07T12:49:48Z VendorInfo=gohugoio
$ dart-sass --version
1.66.1UPD:
docs/content/images/diagram-atlas-db-user-management.png and run$ hugo server --logLevel debug --disableFastRender --renderToDisk
Serving pages from disk
Web Server is available at http://localhost:1313/compose-operator/ (bind address 127.0.0.1)I see is got into rendred to public folder, docs/public/images/diagram-atlas-db-user-management.png, and running locally I can put reference that is working,
Hello, I would like to go directly to the document section to replace the default home page. What should I do?
So I added contentDir: content/docs in the configuration file.
But hextra seems to recognize _index.md in the docs directory as the main page. Therefore the left sidebar will not appear. Even if I use menu: The sidebar: configuration doesn't seem to work either.
Looking forward to your help, this has been bothering me for a long time.
Thanks!!!
Originally posted by msavdert October 2, 2023
https://www.docsy.dev/docs/adding-content/navigation/#section-menu-options
---
title: Configuration
sidebar:
open: false
---This option only works for _index.md. This option didn't work for other .md files under the same folder to not show them in the sidebar.
Summary:
React
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
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
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.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.