mirror of
https://github.com/imfing/hextra.git
synced 2025-08-24 17:16:38 -04:00
6823cc1fe8
* refactor(navbar): add hextra prefix to navbar and hamburger menu classes - Updated CSS class names from `nav-container` to `hextra-nav-container` and `hamburger-menu` to `hextra-hamburger-menu` for improved clarity and consistency across the project. - Adjusted related JavaScript and documentation to reflect the new class names. * refactor(search): update class names for search components - Renamed CSS classes from `search-wrapper`, `search-input`, `active`, `no-result`, `prefix`, `excerpt`, and `match` to `hextra-search-wrapper`, `hextra-search-input`, `hextra-search-active`, `hextra-search-no-result`, `hextra-search-prefix`, `hextra-search-excerpt`, and `hextra-search-match` for improved clarity and consistency. - Updated JavaScript selectors to match the new class names, ensuring functionality remains intact. - Adjusted HTML structure to reflect the new class naming convention. * refactor(search): update search component class names for consistency - Renamed existing search-related CSS classes to include the `hextra` prefix for improved clarity and consistency. - Added optional nested classes for enhanced customization of the search UI, including titles, active states, and result snippets. - Removed outdated breadcrumb section as no specific class is available. * refactor(sidebar): rename sidebar classes for consistency - Updated CSS and JavaScript to replace `sidebar-container` with `hextra-sidebar-container` and `sidebar-active-item` with `hextra-sidebar-active-item` for improved clarity and consistency across the project. - Adjusted related documentation to reflect the new class names. * refactor(language & theme): update class names for consistency - Renamed language switcher and theme toggle classes to include the `hextra` prefix for improved clarity and consistency across the project. - Updated related JavaScript selectors and documentation to reflect the new class names. * refactor(css & html): rename classes for consistency and clarity - Updated various CSS class names to include the `hextra` prefix, enhancing consistency across the project. This includes renaming classes such as `content` to `hextra-content`, `filename` to `hextra-code-filename`, and `steps` to `hextra-steps`. - Adjusted related HTML and JavaScript to reflect the new class names, ensuring functionality and styling remain intact. - Updated documentation to include the new class names for better clarity. * refactor(language): update class names for language options - Renamed the `language-options` class to `hextra-language-options` for consistency with the existing `hextra` prefix convention. - Updated the corresponding HTML to reflect the new class name, ensuring clarity and uniformity across the project. * refactor(css & html): rename classes for consistency and clarity - Renamed CSS classes to include the `hextra` prefix, such as changing `subheading-anchor` to `hextra-subheading-anchor` and `footnotes` to `hextra-footnotes`, enhancing consistency across the project. - Updated related HTML and documentation to reflect the new class names, ensuring clarity and uniformity. * feat(typography): add styling for horizontal lines - Introduced new styles for horizontal lines to enhance visual separation in content. The styles apply margin and border color adjustments, ensuring consistency with the overall design. * feat(blog): add draft release announcement for Hextra v0.10.0 - Created a new markdown file for the draft release announcement of Hextra v0.10.0, including upgrade instructions and author details. - The announcement is currently marked as a draft and may be updated before the official release. * refactor(css & html): rename `hextra-content` class to `content` for consistency - Updated the `hextra-content` class to simply `content` across various HTML files and CSS, enhancing clarity and consistency in the codebase. - Adjusted the `package.json` script for the development server to include the `-F` flag for better functionality. * refactor(typography & markdown): enhance table styling and markdown syntax - Updated CSS for tables to improve styling, including adjustments to margins, borders, and text properties for better readability. - Revised markdown documentation to standardize table formatting and improve clarity, including consistent syntax for headers and lists. - Enhanced examples in the documentation to reflect the updated styling and ensure accurate representation of output. * fix(blog): update text color for improved accessibility - Modified the text color in the blog single layout to enhance readability in dark mode by adding a dark text color class. - Ensured consistency in styling for better user experience across different themes. * docs(blog): update draft release announcement for Hextra v0.10.0 - Revised the "What's New" section to include a TODO placeholder for future updates. - Added a comprehensive migration guide detailing the CSS class prefix changes to enhance consistency and avoid conflicts. - Updated the announcement to reflect the new class naming conventions for various components. * chore: rebuild css
236 lines
6.5 KiB
Markdown
236 lines
6.5 KiB
Markdown
---
|
|
title: Customizing Hextra
|
|
linkTitle: Customization
|
|
---
|
|
|
|
Hextra offers some default customization options in the `hugo.yaml` config file to configure the theme.
|
|
This page describes the available options and how to customize the theme further.
|
|
|
|
<!--more-->
|
|
|
|
## Custom CSS
|
|
|
|
To add custom CSS, we need to create a file `assets/css/custom.css` in our site. Hextra will automatically load this file.
|
|
|
|
### Font Family
|
|
|
|
The font family of the content can be customized using:
|
|
|
|
```css {filename="assets/css/custom.css"}
|
|
.content {
|
|
font-family: "Times New Roman", Times, serif;
|
|
}
|
|
```
|
|
|
|
### Inline Code Element
|
|
|
|
The color of text mixed with `other text` can customized with:
|
|
|
|
```css {filename="assets/css/custom.css"}
|
|
.content code:not(.code-block code) {
|
|
color: #c97c2e;
|
|
}
|
|
```
|
|
|
|
### Primary Color
|
|
|
|
The primary color of the theme can be customized by setting the `--primary-hue`, `--primary-saturation` and `--primary-lightness` variables:
|
|
|
|
```css {filename="assets/css/custom.css"}
|
|
:root {
|
|
--primary-hue: 100deg;
|
|
--primary-saturation: 90%;
|
|
--primary-lightness: 50%;
|
|
}
|
|
```
|
|
|
|
### Component Layout Variables
|
|
|
|
Hextra provides CSS variables to customize the width of pages, navbar, and footer:
|
|
|
|
```css {filename="assets/css/custom.css"}
|
|
:root {
|
|
/* Page width - also configurable via hugo.yaml params.page.width */
|
|
--hextra-max-page-width: 80rem; /* default: 80rem (normal), 90rem (wide), 100% (full) */
|
|
|
|
/* Navbar width - also configurable via hugo.yaml params.navbar.width */
|
|
--hextra-max-navbar-width: 90rem; /* independent navbar width */
|
|
|
|
/* Footer width - also configurable via hugo.yaml params.footer.width */
|
|
--hextra-max-footer-width: 80rem; /* independent footer width */
|
|
}
|
|
```
|
|
|
|
### Further Theme Customization
|
|
|
|
The theme can be further customized by overriding the default styles via the exposed css classes. An example for customizing the footer element:
|
|
|
|
```css {filename="assets/css/custom.css"}
|
|
.hextra-footer {
|
|
/* Styles will be applied to the footer element */
|
|
}
|
|
|
|
.hextra-footer:is(html[class~="dark"] *) {
|
|
/* Styles will be applied to the footer element in dark mode */
|
|
}
|
|
```
|
|
|
|
The following classes can be used to customize various parts of the theme.
|
|
|
|
#### General
|
|
|
|
- `hextra-scrollbar` - The scrollbar element
|
|
- `content` - Page content container
|
|
|
|
#### Shortcodes
|
|
|
|
##### Badge
|
|
|
|
- `hextra-badge` - The badge element
|
|
|
|
##### Card
|
|
|
|
- `hextra-card` - The card element
|
|
- `hextra-card-image` - The card image element
|
|
- `hextra-card-icon` - The card icon element
|
|
- `hextra-card-subtitle` - The card subtitle element
|
|
|
|
##### Cards
|
|
|
|
- `hextra-cards` - The cards grid container
|
|
|
|
##### Jupyter Notebook
|
|
|
|
- `hextra-jupyter-code-cell` - The Jupyter code cell container
|
|
- `hextra-jupyter-code-cell-outputs-container` - The Jupyter code cell outputs container
|
|
- `hextra-jupyter-code-cell-outputs` - The Jupyter code cell output div element
|
|
|
|
##### PDF
|
|
|
|
- `hextra-pdf` - The PDF container element
|
|
|
|
##### Steps
|
|
|
|
- `hextra-steps` - The steps container
|
|
|
|
##### Tabs
|
|
|
|
- `hextra-tabs-panel` - The tabs panel container
|
|
- `hextra-tabs-toggle` - The tabs toggle button
|
|
|
|
##### Filetree
|
|
|
|
- `hextra-filetree` - The filetree container
|
|
|
|
##### Folder
|
|
|
|
- `hextra-filetree-folder` - The filetree folder container
|
|
|
|
#### Navbar
|
|
|
|
- `hextra-nav-container` - The navbar container
|
|
- `hextra-nav-container-blur` - The navbar container in blur element
|
|
- `hextra-hamburger-menu` - The hamburger menu button
|
|
|
|
#### Footer
|
|
|
|
- `hextra-footer` - The footer element
|
|
- `hextra-custom-footer` - The custom footer section container
|
|
|
|
#### Search
|
|
|
|
- `hextra-search-wrapper` - The search wrapper container
|
|
- `hextra-search-input` - The search input element
|
|
- `hextra-search-results` - The search results list container
|
|
|
|
Optional nested classes used within the search UI:
|
|
|
|
- `hextra-search-title` - The result title element
|
|
- `hextra-search-active` - The active result anchor
|
|
- `hextra-search-no-result` - The empty state element
|
|
- `hextra-search-prefix` - The breadcrumb/prefix label for grouped results
|
|
- `hextra-search-excerpt` - The result snippet text
|
|
- `hextra-search-match` - The highlighted query span
|
|
|
|
#### Table of Contents
|
|
|
|
- `hextra-toc` - The table of contents container
|
|
|
|
#### Sidebar
|
|
|
|
- `hextra-sidebar-container` - The sidebar container
|
|
- `hextra-sidebar-active-item` - The active item in the sidebar
|
|
|
|
#### Language Switcher
|
|
|
|
- `hextra-language-switcher` - The language switcher button
|
|
- `hextra-language-options` - The language options container
|
|
|
|
#### Theme Toggle
|
|
|
|
- `hextra-theme-toggle` - The theme toggle button
|
|
|
|
#### Code Copy Button
|
|
|
|
- `hextra-code-copy-btn-container` - The code copy button container
|
|
- `hextra-code-copy-btn` - The code copy button
|
|
- `hextra-copy-icon` - The copy icon element
|
|
- `hextra-success-icon` - The success icon element
|
|
|
|
#### Code Block
|
|
|
|
- `hextra-code-block` - The code block container
|
|
- `hextra-code-filename` - The filename element for code blocks
|
|
|
|
#### Feature Card
|
|
|
|
- `hextra-feature-card` - The feature card link element
|
|
|
|
#### Feature Grid
|
|
|
|
- `hextra-feature-grid` - The feature grid container
|
|
|
|
### Syntax Highlighting
|
|
|
|
List of available syntax highlighting themes are available at [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html). The stylesheet can be generated using the command:
|
|
|
|
```shell
|
|
hugo gen chromastyles --style=github
|
|
```
|
|
|
|
To override the default syntax highlighting theme, we can add the generated styles to the custom CSS file.
|
|
|
|
## Custom Scripts
|
|
|
|
You may add custom scripts to the end of the head for every page by adding the following file:
|
|
|
|
```
|
|
layouts/partials/custom/head-end.html
|
|
```
|
|
|
|
## Custom Extra Section in Footer
|
|
|
|
You can add extra section in the footer by creating a file `layouts/partials/custom/footer.html` in your site.
|
|
|
|
```html {filename="layouts/partials/custom/footer.html"}
|
|
<!-- Your footer element here -->
|
|
```
|
|
|
|
The added section will be added before the copyright section in the footer.
|
|
You can use [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) and [Hugo template syntax](https://gohugo.io/templates/) to add your own content.
|
|
|
|
Hugo variables available in the footer section are: `.switchesVisible` and `.displayCopyright`.
|
|
|
|
## Custom Layouts
|
|
|
|
The layouts of the theme can be overridden by creating a file with the same name in the `layouts` directory of your site.
|
|
For example, to override the `single.html` layout for docs, create a file `layouts/docs/single.html` in your site.
|
|
|
|
For further information, refer to the [Hugo Templates][hugo-template-docs].
|
|
|
|
## Further Customization
|
|
|
|
Didn't find what you were looking for? Feel free to [open a discussion](https://github.com/imfing/hextra/discussions) or make a contribution to the theme!
|
|
|
|
[hugo-template-docs]: https://gohugo.io/templates/
|