mirror of
https://github.com/tiennm99/HugoBlox-kit.git
synced 2026-10-17 04:14:26 +00:00
starters: standardise starters dir name to templates
This commit is contained in:
George Cushen committed
1 parent
20a6f8202e
commit
5f2290d590
280 files changed
+4473
-231
No files matched your search
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: Guide
|
||||
weight: 2
|
||||
sidebar:
|
||||
open: true
|
||||
---
|
||||
|
||||
{{< cards >}}
|
||||
{{< card url="project-structure" title="Project Structure" icon="document-duplicate" >}}
|
||||
{{< card url="configuration" title="Configuration" icon="adjustments-vertical" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Configuration
|
||||
weight: 2
|
||||
---
|
||||
|
||||
The configuration of your site can be found in `config/_default/`.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Full Documentation
|
||||
|
||||
See https://docs.hugoblox.com/getting-started/customize/
|
||||
|
||||
## Navigation
|
||||
|
||||
### Menu
|
||||
|
||||
See https://docs.hugoblox.com/getting-started/customize/#menu-items
|
||||
|
||||
## Left Sidebar
|
||||
|
||||
Links are automatically generated from the structure of your content directory. Simply add a folder to nest a page.
|
||||
|
||||
### Extra Links
|
||||
|
||||
Additional links can be added under the `sidebar` section of your `config/_default/menus.yaml`:
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
sidebar:
|
||||
- name: "Need help?"
|
||||
params:
|
||||
type: separator
|
||||
weight: 1
|
||||
- name: "A page"
|
||||
pageRef: "/page-filename-here"
|
||||
weight: 2
|
||||
- name: "An external link ↗"
|
||||
url: "https://hugoblox.com"
|
||||
weight: 3
|
||||
```
|
||||
|
||||
## Right Sidebar
|
||||
|
||||
A table of contents is automatically generated from the headings your Markdown file.
|
||||
|
||||
It can optionally be disabled by setting `toc: false` in the front matter of a page:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My Page
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Project Structure
|
||||
weight: 1
|
||||
---
|
||||
|
||||
## Folder Structure
|
||||
|
||||
There are **4 main folders for Hugo-based sites**:
|
||||
|
||||
- `content/` for your Markdown-formatted content files (homepage, etc.)
|
||||
- `_index.md` the homepage (**Hugo requires that the homepage and archive pages have an underscore prefix**)
|
||||
- `assets/`
|
||||
- `media/` for your media files (images, videos)
|
||||
- `icons/custom/` upload any custom SVG icons you want to use
|
||||
- `config/_default/` for your site configuration files
|
||||
- `hugo.yaml` to configure Hugo (site title, URL, Hugo options, setup per-folder page features)
|
||||
- `module.yaml` to install or uninstall Hugo themes and plugins
|
||||
- `params.yaml` to configure Hugo Blox options (SEO, analytics, site features)
|
||||
- `menus.yaml` to configure your menu links (if the menu is enabled in `params.yaml`)
|
||||
- `languages.yaml` to configure your site's language or to set language-specific options in a multilingual site
|
||||
- `static/uploads/` for any files you want visitors to download, such as a PDF
|
||||
- `go.mod` sets the version of Hugo themes/plugins which your site uses
|
||||
|
||||
|
||||
## Hugo File Naming Convention
|
||||
|
||||
Hugo gives us two options to name standard page files: as `TITLE/index.md` or `TITLE.md` where `TITLE` is your page name.
|
||||
|
||||
The page name should be lowercase and using hyphens (`-`) instead of spaces.
|
||||
|
||||
Both approaches result in the same output, so you can choose your preferred approach to naming and organizing files. A benefit to the folder-based approach is that all your page's files (such as images) are self-contained within the page's folder, so it's more portable if you wish to share the original Markdown page with someone.
|
||||
|
||||
The homepage is a special case as **Hugo requires the homepage and listing pages to be named** `_index.md`.
|
||||
|
||||
## Docs Navigation
|
||||
|
||||
The docs navigation is automatically generated based on the content in the `docs/` folder and is sorted alphabetically.
|
||||
|
||||
The order of pages can be changed by adding the `weight` parameter in the front matter of your Markdown files.
|
||||
|
||||
In the example below, the `example.md` page will appear before the `test.md` page as it has a lower `weight`:
|
||||
|
||||
Page `example.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My Example
|
||||
weight: 1
|
||||
---
|
||||
```
|
||||
|
||||
Page `test.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My Test
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Shortcodes
|
||||
---
|
||||
|
||||
Build the best docs with re-usable components, referred to as Hugo shortcodes:
|
||||
|
||||
{{< cards >}}
|
||||
{{< card url="button" title="Button" icon="cursor-arrow-rays" >}}
|
||||
{{< card url="callout" title="Callout" icon="warning" >}}
|
||||
{{< card url="cards" title="Cards" icon="card" >}}
|
||||
{{< card url="toggle" title="Spoiler" icon="chevron-right" >}}
|
||||
{{< card url="steps" title="Steps" icon="one" >}}
|
||||
{{< /cards >}}
|
||||
@@ -0,0 +1,202 @@
|
||||
---
|
||||
title: Button Shortcode
|
||||
linkTitle: Button
|
||||
---
|
||||
|
||||
A modern, customizable button shortcode with gradient styling, icons, and smart link handling.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Basic Usage
|
||||
|
||||
{{< button url="/contact" >}}Contact Us{{< /button >}}
|
||||
|
||||
{{< button url="https://example.com" new_tab="true" style="secondary" >}}Visit External Site{{< /button >}}
|
||||
|
||||
The above buttons are created with:
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="/contact" */>}}Contact Us{{</* /button */>}}
|
||||
|
||||
{{</* button url="https://example.com" new_tab="true" style="secondary" */>}}Visit External Site{{</* /button */>}}
|
||||
```
|
||||
|
||||
## Style Variants
|
||||
|
||||
### Primary (Default)
|
||||
|
||||
{{< button url="#" style="primary" >}}Primary Button{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" style="primary" */>}}Primary Button{{</* /button */>}}
|
||||
```
|
||||
|
||||
### Secondary
|
||||
|
||||
{{< button url="#" style="secondary" >}}Secondary Button{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" style="secondary" */>}}Secondary Button{{</* /button */>}}
|
||||
```
|
||||
|
||||
### Outline
|
||||
|
||||
{{< button url="#" style="outline" >}}Outline Button{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" style="outline" */>}}Outline Button{{</* /button */>}}
|
||||
```
|
||||
|
||||
### Ghost
|
||||
|
||||
{{< button url="#" style="ghost" >}}Ghost Button{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" style="ghost" */>}}Ghost Button{{</* /button */>}}
|
||||
```
|
||||
|
||||
## Sizes
|
||||
|
||||
### Small
|
||||
|
||||
{{< button url="#" size="sm" >}}Small Button{{< /button >}}
|
||||
|
||||
### Medium (Default)
|
||||
|
||||
{{< button url="#" size="md" >}}Medium Button{{< /button >}}
|
||||
|
||||
### Large
|
||||
|
||||
{{< button url="#" size="lg" >}}Large Button{{< /button >}}
|
||||
|
||||
### Extra Large
|
||||
|
||||
{{< button url="#" size="xl" >}}Extra Large{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" size="sm" */>}}Small Button{{</* /button */>}}
|
||||
{{</* button url="#" size="md" */>}}Medium Button{{</* /button */>}}
|
||||
{{</* button url="#" size="lg" */>}}Large Button{{</* /button */>}}
|
||||
{{</* button url="#" size="xl" */>}}Extra Large{{</* /button */>}}
|
||||
```
|
||||
|
||||
## Alignment
|
||||
|
||||
### Left (Default)
|
||||
|
||||
{{< button url="#" align="left" >}}Left Aligned{{< /button >}}
|
||||
|
||||
### Center
|
||||
|
||||
{{< button url="#" align="center" >}}Center Aligned{{< /button >}}
|
||||
|
||||
### Right
|
||||
|
||||
{{< button url="#" align="right" >}}Right Aligned{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" align="left" */>}}Left Aligned{{</* /button */>}}
|
||||
{{</* button url="#" align="center" */>}}Center Aligned{{</* /button */>}}
|
||||
{{</* button url="#" align="right" */>}}Right Aligned{{</* /button */>}}
|
||||
```
|
||||
|
||||
## With Icons
|
||||
|
||||
### Icon Before Text
|
||||
|
||||
{{< button url="#" icon="download" >}}Download{{< /button >}}
|
||||
|
||||
### Icon After Text
|
||||
|
||||
{{< button url="#" icon="arrow-right" icon_position="right" >}}Continue{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" icon="download" */>}}Download{{</* /button */>}}
|
||||
{{</* button url="#" icon="arrow-right" icon_position="right" */>}}Continue{{</* /button */>}}
|
||||
```
|
||||
|
||||
## Rounded Corners
|
||||
|
||||
### Small Radius
|
||||
|
||||
{{< button url="#" rounded="sm" >}}Small Radius{{< /button >}}
|
||||
|
||||
### Medium Radius (Default)
|
||||
|
||||
{{< button url="#" rounded="md" >}}Medium Radius{{< /button >}}
|
||||
|
||||
### Large Radius
|
||||
|
||||
{{< button url="#" rounded="lg" >}}Large Radius{{< /button >}}
|
||||
|
||||
### Pill Shape
|
||||
|
||||
{{< button url="#" rounded="full" >}}Pill Button{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="#" rounded="sm" */>}}Small Radius{{</* /button */>}}
|
||||
{{</* button url="#" rounded="md" */>}}Medium Radius{{</* /button */>}}
|
||||
{{</* button url="#" rounded="lg" */>}}Large Radius{{</* /button */>}}
|
||||
{{</* button url="#" rounded="full" */>}}Pill Button{{</* /button */>}}
|
||||
```
|
||||
|
||||
## Advanced Examples
|
||||
|
||||
### Call-to-Action Button
|
||||
|
||||
{{< button url="/signup" style="primary" size="lg" align="center" icon="rocket-launch" >}}Get Started Today{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="/signup" style="primary" size="lg" align="center" icon="rocket-launch" */>}}Get Started Today{{</* /button */>}}
|
||||
```
|
||||
|
||||
### External Link with New Tab
|
||||
|
||||
{{< button url="https://github.com/hugo-blox/hugo-blox-builder" new_tab="true" style="outline" icon="arrow-top-right-on-square" icon_position="right" >}}View on GitHub{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="https://github.com/hugo-blox/hugo-blox-builder" new_tab="true" style="outline" icon="arrow-top-right-on-square" icon_position="right" */>}}View on GitHub{{</* /button */>}}
|
||||
```
|
||||
|
||||
### Download Button
|
||||
|
||||
{{< button url="/files/document.pdf" style="secondary" icon="document-arrow-down" rounded="full" >}}Download PDF{{< /button >}}
|
||||
|
||||
```go-html-template
|
||||
{{</* button url="/files/document.pdf" style="secondary" icon="document-arrow-down" rounded="full" */>}}Download PDF{{</* /button */>}}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| --------------- | ------- | ------------- | ----------------------------------------------------------- |
|
||||
| `url` | string | `#` | **Required.** Button destination URL (internal or external) |
|
||||
| `text` | string | Inner content | Button text (overrides shortcode content) |
|
||||
| `new_tab` | boolean | `false` | Whether to open link in new tab |
|
||||
| `style` | string | `primary` | Button style: `primary`, `secondary`, `outline`, `ghost` |
|
||||
| `size` | string | `md` | Button size: `sm`, `md`, `lg`, `xl` |
|
||||
| `align` | string | `left` | Button alignment: `left`, `center`, `right` |
|
||||
| `icon` | string | - | Icon name from [Hero Icons](https://heroicons.com/) |
|
||||
| `icon_position` | string | `left` | Icon position: `left`, `right` |
|
||||
| `rounded` | string | `md` | Border radius: `sm`, `md`, `lg`, `xl`, `full` |
|
||||
| `disabled` | boolean | `false` | Whether button should be disabled |
|
||||
|
||||
## Security Features
|
||||
|
||||
The button shortcode automatically handles security for external links:
|
||||
|
||||
- **External links** get `rel="noreferrer"` attribute
|
||||
- **External links opening in new tab** get `rel="noopener noreferrer"`
|
||||
- **Internal links opening in new tab** get `rel="noopener"`
|
||||
|
||||
This ensures safe navigation while maintaining functionality.
|
||||
|
||||
## Accessibility
|
||||
|
||||
The button shortcode includes built-in accessibility features:
|
||||
|
||||
- Proper `role="button"` attribute
|
||||
- `aria-label` support
|
||||
- Keyboard focus indicators
|
||||
- High contrast focus rings
|
||||
- Disabled state handling
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Callout Shortcode
|
||||
linkTitle: Callout
|
||||
---
|
||||
|
||||
Hugo Blox supports a Markdown extension for callouts, also referred to as alerts or asides.
|
||||
|
||||
Callouts are a useful feature to draw attention to important or related content such as notes, hints, or warnings in your articles.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Usage
|
||||
|
||||
### Notes
|
||||
|
||||
> [!NOTE]
|
||||
> A Markdown callout is useful for displaying notices, hints, or definitions to your readers.
|
||||
|
||||
```markdown
|
||||
> [!NOTE]
|
||||
> A Markdown callout is useful for displaying notices, hints, or definitions to your readers.
|
||||
```
|
||||
|
||||
### Warnings
|
||||
|
||||
> [!WARNING]
|
||||
> Here's some important information...
|
||||
|
||||
```markdown
|
||||
> [!WARNING]
|
||||
> Here's some important information...
|
||||
```
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Cards Shortcode
|
||||
linkTitle: Cards
|
||||
---
|
||||
|
||||
A Hugo extension to create cards. Cards can be shown as links or as plain text.
|
||||
|
||||
## Usage
|
||||
|
||||
{{< cards >}}
|
||||
{{< card url="../" title="Learn Shortcodes" icon="academic-cap" >}}
|
||||
{{< card url="" title="A card without an icon or link" >}}
|
||||
{{< /cards >}}
|
||||
|
||||
is rendered by:
|
||||
|
||||
```
|
||||
{{</* cards */>}}
|
||||
{{</* card url="../callout" title="Callout" icon="academic-cap" */>}}
|
||||
{{</* card url="" title="A card without an icon" */>}}
|
||||
{{</* /cards */>}}
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Parameter | Description |
|
||||
|------------|------------------------------------------------------------------------|
|
||||
| `icon` | Name of the icon. Defaults to [Hero Icon Pack](https://heroicons.com/) |
|
||||
| `title` | Title heading for the card. |
|
||||
| `subtitle` | Subtitle heading (supports Markdown). |
|
||||
| `url` | URL |
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: Steps Shortcode
|
||||
linkTitle: Steps
|
||||
---
|
||||
|
||||
Display a series of steps, such as for a tutorial.
|
||||
|
||||
## Example
|
||||
|
||||
{{% steps %}}
|
||||
|
||||
### Step 1
|
||||
|
||||
The first step here...
|
||||
|
||||
### Step 2
|
||||
|
||||
The second step here...
|
||||
|
||||
### Step 3
|
||||
|
||||
The third step here...
|
||||
|
||||
{{% /steps %}}
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Use the Markdown level-3 headings to represent step titles within the `steps` shortcode:
|
||||
|
||||
```
|
||||
{{%/* steps */%}}
|
||||
|
||||
### Step 1
|
||||
|
||||
The first step here...
|
||||
|
||||
### Step 2
|
||||
|
||||
The second step here...
|
||||
|
||||
### Step 3
|
||||
|
||||
The third step here...
|
||||
|
||||
{{%/* /steps */%}}
|
||||
```
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Spoiler
|
||||
---
|
||||
|
||||
A Hugo shortcode to toggle collapsible content.
|
||||
|
||||
<!--more-->
|
||||
|
||||
## Example
|
||||
|
||||
{{< spoiler text="Click to view the spoiler" >}}
|
||||
You found me!
|
||||
|
||||
Markdown is **supported**.
|
||||
{{< /spoiler >}}
|
||||
|
||||
## Usage
|
||||
|
||||
````
|
||||
{{</* spoiler text="Click to view the spoiler" */>}}
|
||||
|
||||
This is the content of the details.
|
||||
|
||||
Markdown is **supported**.
|
||||
|
||||
{{</* /spoiler */>}}
|
||||
````
|
||||
Reference in new issue
Block a user