The GitHub repo for Hugo Admonitions is at https://github.com/KKKZOZ/hugo-admonitions

By adding Hugo Admonitions to your website so you can easily add stylish note bars for things like tips, warnings, cautions, important information etc. You can do this quickly and easily directly using markdown.

I used this feature with other systems and when looking into how to do this with Hugo I found blog/forum posts linking to a deleted github repo and for this reason I have decided to include the files inside my Hugo Website rather then using Hugo Modules or git submodules. This way I always have a working copy that I control and less risk of my website breaking due to deleted github repos.

Downloading the GitHub repo and preparing it for inclusion to your Hugo website

Outside of your hugo installation run the following command:

git clone git@github.com:KKKZOZ/hugo-admonitions.git themes/hugo-admonitions --depth=1
The –depth=1 tells git to only download the most current commit and not all the git history.

Now you need to delete the .git and .github directories from the theme download so it does not conflict with your repo.

rm -Rf themes/hugo-admonitions/.git
rm -Rf themes/hugo-admonitions/.github

Now you can copy the Hugo Admonitions theme into your Hugo website.

cp -Rf themes/hugo-admonitions /your/hugo/path/themes
cd /your/hugo/path

Registering the Hugo Admonitions Theme

Inside your Hugo root directory edit your hugo.toml configuration file and set the theme to be the following:

theme = ['hugo-admonitions', 'your-theme-name']

The Hugo Admonitions theme must appear before your main theme. This allows Hugo to load the admonition shortcodes and styles first.

Your theme should be the last theme entry at the very end

You should now be able to use Hugo Admonitions inside your markdown files.

Example Usage

I am going to provide a large list of the options that can be used. First you will see what it looks like on the website then you will see the markdown code on how to use them.

For a full list you should check out the Hugo Admonitions GitHub Demos at https://github.com/KKKZOZ/hugo-admonitions/blob/main/docs/content/demo.md?plain=1

GitHub Style

Note

Useful information that users should know, even when skimming content.

> [!NOTE]
> Useful information that users should know, even when skimming content.
Tip

Helpful advice for doing things better or more easily.

> [!TIP]
> Helpful advice for doing things better or more easily.
Important

Key information users need to know to achieve their goal.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.
Warning

Urgent info that needs immediate user attention to avoid problems.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
Caution

Advises about risks or negative outcomes of certain actions.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Callout Style

Abstract

Abstract: This paper discusses the advantages and challenges of microservice architecture.

> [!ABSTRACT]
> Abstract: This paper discusses the advantages and challenges of microservice architecture.
Caution

Advises about risks or negative outcomes of certain actions.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
Code

Code snippet:

function fetchData() {
    return axios.get('/api/data');
}

> [!CODE]
> Code snippet:
>
> ```javascript
> function fetchData() {
>     return axios.get('/api/data');
> }
> ```
Conclusion

Conclusion: Based on the analysis above, we’ve decided to implement Docker containerization.

> [!CONCLUSION]
> Conclusion: Based on the analysis above, we've decided to implement Docker containerization.
Danger

Danger! Critical security vulnerability detected in the system. Immediate action required.

> [!DANGER]
> Danger! Critical security vulnerability detected in the system. Immediate action required.
Error

Error: Unable to connect to database. Please check your connection settings.

> [!ERROR]
> Error: Unable to connect to database. Please check your connection settings.
Example

Example:

def hello_world():
    print("Hello, World!")

> [!EXAMPLE]
> Example:
>
> ```python
> def hello_world():
>     print("Hello, World!")
> ```
Experiment

Experiment: Testing the impact of new caching strategies on system performance.

> [!EXPERIMENT]
> Experiment: Testing the impact of new caching strategies on system performance.
Goal

Goal: Reduce service response time by 30% by the end of this quarter.

> [!GOAL]
> Goal: Reduce service response time by 30% by the end of this quarter.
Idea

Idea: Implement a machine learning-based code quality detection system.

> [!IDEA]
> Idea: Implement a machine learning-based code quality detection system.
Success

Congratulations! Your code has been successfully deployed to production.

> [!SUCCESS]
> Congratulations! Your code has been successfully deployed to production.
Task

To-do list:

  • Update documentation
  • Deploy new version
> [!TASK]
> To-do list:
> - Update documentation  
> - Deploy new version
Tip

Helpful advice for doing things better or more easily.

> [!TIP]
> Helpful advice for doing things better or more easily.
Warning

Urgent info that needs immediate user attention to avoid problems.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

Header Only Style

This paper discusses the advantages of microservice architecture
> [!ABSTRACT] This paper discusses the advantages of microservice architecture
Ensure all tests pass before merging to main branch
> [!CAUTION] Ensure all tests pass before merging to main branch
Execute npm install to install all dependencies
> [!CODE] Execute `npm install` to install all dependencies
We’ve decided to implement Docker containerization
> [!CONCLUSION] We've decided to implement Docker containerization
Critical security vulnerability detected in the system
> [!DANGER] Critical security vulnerability detected in the system
Error: Unable to connect to database. Please check your connection settings
> [!ERROR] Error: Unable to connect to database. Please check your connection settings
Git commit message format: “feat: add user authentication”
> [!EXAMPLE] Git commit message format: "feat: add user authentication"
Testing new caching strategy with Redis
> [!EXPERIMENT] Testing new caching strategy with Redis
Reduce service response time by 30% by the end of this quarter
> [!GOAL] Reduce service response time by 30% by the end of this quarter
Implement a machine learning-based code quality detection system
> [!IDEA] Implement a machine learning-based code quality detection system
Please review and update your security settings
> [!IMPORTANT] Please review and update your security settings
Current system status: All services are operating normally with 99.9% uptime
> [!INFO] Current system status: All services are operating normally with 99.9% uptime
Technical review meeting scheduled for next Tuesday at 2:00 PM
> [!MEMO] Technical review meeting scheduled for next Tuesday at 2:00 PM
Always backup your data before performing system updates
> [!NOTE] Always backup your data before performing system updates
System notification: Your password will expire in 30 days
> [!NOTIFY] System notification: Your password will expire in 30 days
How can we optimize database query performance?
> [!QUESTION] How can we optimize database query performance?
“Code is like humor. When you have to explain it, it’s bad.” - Cory House
> [!QUOTE] "Code is like humor. When you have to explain it, it's bad." - Cory House
Congratulations! Your code has been successfully deployed to production
> [!SUCCESS] Congratulations! Your code has been successfully deployed to production
Review and update API documentation by Friday
> [!TASK] Review and update API documentation by Friday
Use Ctrl + C to quickly terminate a running program
> [!TIP] Use `Ctrl + C` to quickly terminate a running program
Warning: This operation will delete all data
> [!WARNING] Warning: This operation will delete all data

Conclusion

If you have set this up correctly then you should be able to use Hugo Admonitions in your markdown to quickly and easily create stylish note bars.

Tags:

Latest Blog Posts: