diff --git a/README.md b/README.md index d9ea573bbb..272b08fba1 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,79 @@ # Hugo Relearn Theme -A theme for [Hugo](https://gohugo.io/) designed for documentation. +A theme for [Hugo](https://gohugo.io/), designed for documentation. + +[★ What's new in the latest release ★](https://mcshelby.github.io/hugo-theme-relearn/basics/migration) ![Overview](https://github.com/McShelby/hugo-theme-relearn/raw/main/images/hero.png) ## Motivation -The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo-theme-learn) with the aim of fixing long outstanding bugs and adepting to latest Hugo features. As far as possible this theme tries to be a drop-in replacement for the Learn theme. +The Relearn theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo-theme-learn) with the aim of fixing long outstanding bugs and adepting to latest Hugo features. As far as possible this theme tries to be a drop-in replacement for the Learn theme. ## Features -- Usable offline, no external dependencies -- Usable without a HTTP server from the file system -- Support for Internet Explorer 11 -- Responsive design -- Configurable hidden pages -- Automatic next/prev buttons to navigate through menu entries -- Automatic Search -- Dedicated search page -- Support for GFM (GitHub Flavored Markdown) -- Print whole chapters or even the complete site -- Multilingual mode for English, Arabic, Simplified Chinese, Traditional Chinese, Czech, Dutch, Finnish, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese -- Full support for languages written right to left -- Unrestricted menu configuration relating to amount of items and level of nesting -- Font Awesome icons -- Tagging support -- Image styling like sizing, shadow, border and alignment -- Syntax highlighting -- Customizable look and feel -- Predefined (light, dark) and customizable color variants -- Automatic switch for light/dark mode dependend on your OS settings -- Attachments files -- List child pages -- Math and chemical formulae using the MathJax library -- Mermaid diagrams for flowcharts, sequences, gantts, pie, etc. -- Swagger UI for OpenAPI Specifications -- Badges -- Buttons -- Tip/Note/Info/Warning boxes -- Expand -- Tabs -- File inclusion +- **Wide set of usage scenarios** + - Responsive design for mobile usage + - Looks nice on paper (if you have to) + - Usable offline, no external dependencies + - [Usable from your local file system via `file://` protocol](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#serving-your-page-from-the-filesystem) + - Support for Internet Explorer 11 +- **Configurable theming and visuals** + - [Configurable brand images](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#change-the-logo) + - [Automatic switch for light/dark variant dependend on your OS settings](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#adjusting-to-os-settings) + - Predefined light, dark and color variants + - [User selectable variants](https://mcshelby.github.io/hugo-theme-relearn/basics/customization#multiple-variants) + - [Stylesheet generator](https://mcshelby.github.io/hugo-theme-relearn/basics/generator) + - [Configurable syntax highlighting](https://mcshelby.github.io/hugo-theme-relearn/cont/syntaxhighlight) +- **Unique theme features** + - [Print whole chapters or even the complete site](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#activate-print-support) + - In page search + - [Site search](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#activate-search) + - [Dedicated search page](https://mcshelby.github.io/hugo-theme-relearn/basics/configuration#activate-dedicated-search-page) + - [Tagging support](https://mcshelby.github.io/hugo-theme-relearn/cont/tags) + - Hidden pages + - Unlimited nested menu dependend on your site structure + - Navigation buttons dependend on your site structure + - [Configurable shortcut links](https://mcshelby.github.io/hugo-theme-relearn/cont/menushortcuts) +- **Multi language support** + - [Full support for languages written right to left](https://mcshelby.github.io/hugo-theme-relearn/cont/i18n) + - [Arabic, Simplified Chinese, Traditional Chinese, Czech, Dutch, English, Finnish, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese](https://mcshelby.github.io/hugo-theme-relearn/cont/i18n#basic-configuration) + - [Search support for mixed language content](https://mcshelby.github.io/hugo-theme-relearn/cont/i18n#search) +- **Additional Markdown features** + - [Support for GFM (GitHub Flavored Markdown](https://mcshelby.github.io/hugo-theme-relearn/cont/markdown) + - [Image styling like sizing, shadow, border and alignment](https://mcshelby.github.io/hugo-theme-relearn/cont/markdown#further-image-formatting) + - [Image lightbox](https://mcshelby.github.io/hugo-theme-relearn/cont/markdown#further-image-formatting#lightbox) +- **Shortcodes galore** + - [Display files attached to page bundles](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/attachments) + - [Marker badges](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/badge) + - [Configurable buttons](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/button) + - [List child pages](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/children) + - [Expand areas to reveal content](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/expand) + - [Font Awesome icons](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/icon) + - [Inclusion of other files](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/include) + - [Math and chemical formulae using MathJax](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/math) + - [Mermaid diagrams for flowcharts, sequences, gantts, pie, etc.](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/mermaid) + - [Colorful boxes](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/notice) + - [Reveal you site's configuration parameter](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/siteparam) + - [Swagger UI for your OpenAPI Specifications](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/swagger) + - [Tabbed panels](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tabs) -## Installation +## Installation & Usage -Visit the [installation instructions](https://mcshelby.github.io/hugo-theme-relearn/basics/installation) to learn how to setup the theme in your Hugo installation. - -## Usage - -Visit the [documentation](https://mcshelby.github.io/hugo-theme-relearn/) to learn about all available features and how to use them. +For a detailed description of the theme's capabilities visit the [official documentation](https://mcshelby.github.io/hugo-theme-relearn/). ## Changelog -See the [What's New](https://mcshelby.github.io/hugo-theme-relearn/basics/migration) page for release highlights or the [history](https://mcshelby.github.io/hugo-theme-relearn/basics/history) for a complete list of changes per release. +See the [What's New](https://mcshelby.github.io/hugo-theme-relearn/basics/migration) page for release highlights or the detailed [change history](https://mcshelby.github.io/hugo-theme-relearn/basics/history) for a complete list of changes. -## Contribution +## Contributions -You are most welcome to contribute bugfixes or even new features to the source code. Please visit the [contribution guidelines](https://mcshelby.github.io/hugo-theme-relearn/dev/contributing) first. +You are most welcome to contribute bugfixes or even new features to the source code. Check the [contribution guidelines](https://mcshelby.github.io/hugo-theme-relearn/dev/contributing) first before making any changes. ## License -This theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE). +The Relearn theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE). ## Credits -Special thanks to [everyone who has contributed](https://github.com/McShelby/hugo-theme-relearn/graphs/contributors) to this project. - -Many thanks to [Mathieu Cornic](https://github.com/matcornic) for his work on porting the [Learn theme](https://github.com/matcornic/hugo-theme-learn) to Hugo. - -Many thanks to [Andy Miller](https://github.com/rhukster) for initially creating the [Learn theme](https://github.com/getgrav/grav-theme-learn2) for Grav. - -See the [credits](https://mcshelby.github.io/hugo-theme-relearn/more/credits) for a detailed list. +This theme would not be possible without the work of [many others](https://mcshelby.github.io/hugo-theme-relearn/more/credits). diff --git a/exampleSite/content/_index.en.md b/exampleSite/content/_index.en.md index df367649f5..2c543df740 100644 --- a/exampleSite/content/_index.en.md +++ b/exampleSite/content/_index.en.md @@ -3,64 +3,78 @@ archetype = "home" title = "Hugo Relearn Theme" +++ -The [Relearn theme](https://github.com/McShelby/hugo-theme-relearn) is a theme for [Hugo](https://gohugo.io/), a static website generator written in Go. Where Hugo is often used for blogs, this theme is designed with documentation in mind. +A theme for [Hugo](https://gohugo.io/), designed for documentation. + +[★ What's new in the latest release ★]({{% relref "basics/migration" %}}) + +![Overview](images/hero.png) + +## Motivation -{{% notice info %}} The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo-theme-learn) with the aim of fixing long outstanding bugs and adepting to latest Hugo features. As far as possible this theme tries to be a drop-in replacement for the Learn theme. -{{% /notice %}} ## Features -{{% notice tip %}} -See [What's New]({{% relref "basics/migration" %}}) within the latest update. -{{% /notice %}} +- **Wide set of usage scenarios** + - Responsive design for mobile usage + - Looks nice on paper (if you have to) + - Usable offline, no external dependencies + - [Usable from your local file system via `file://` protocol]({{%relref "basics/configuration#serving-your-page-from-the-filesystem" %}}) + - Support for Internet Explorer 11 +- **Configurable theming and visuals** + - [Configurable brand images]({{%relref "basics/customization#change-the-logo" %}}) + - [Automatic switch for light/dark variant dependend on your OS settings]({{%relref "basics/customization#adjusting-to-os-settings" %}}) + - Predefined light, dark and color variants + - [User selectable variants]({{%relref "basics/customization#multiple-variants" %}}) + - [Stylesheet generator]({{%relref "basics/generator" %}}) + - [Configurable syntax highlighting]({{%relref "cont/syntaxhighlight" %}}) +- **Unique theme features** + - [Print whole chapters or even the complete site]({{%relref "basics/configuration#activate-print-support" %}}) + - In page search + - [Site search]({{%relref "basics/configuration#activate-search" %}}) + - [Dedicated search page]({{%relref "basics/configuration#activate-dedicated-search-page" %}}) + - [Tagging support]({{%relref "cont/tags" %}}) + - Hidden pages + - Unlimited nested menu dependend on your site structure + - Navigation buttons dependend on your site structure + - [Configurable shortcut links]({{%relref "cont/menushortcuts" %}}) +- **Multi language support** + - [Full support for languages written right to left]({{%relref "cont/i18n" %}}) + - [Arabic, Simplified Chinese, Traditional Chinese, Czech, Dutch, English, Finnish, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese]({{%relref "cont/i18n#basic-configuration" %}}) + - [Search support for mixed language content]({{%relref "cont/i18n#search" %}}) +- **Additional Markdown features** + - [Support for GFM (GitHub Flavored Markdown]({{%relref "cont/markdown" %}}) + - [Image styling like sizing, shadow, border and alignment]({{%relref "cont/markdown#further-image-formatting" %}}) + - [Image lightbox]({{%relref "cont/markdown#further-image-formatting#lightbox" %}}) +- **Shortcodes galore** + - [Display files attached to page bundles]({{%relref "shortcodes/attachments" %}}) + - [Marker badges]({{%relref "shortcodes/badge" %}}) + - [Configurable buttons]({{%relref "shortcodes/button" %}}) + - [List child pages]({{%relref "shortcodes/children" %}}) + - [Expand areas to reveal content]({{%relref "shortcodes/expand" %}}) + - [Font Awesome icons]({{%relref "shortcodes/icon" %}}) + - [Inclusion of other files]({{%relref "shortcodes/include" %}}) + - [Math and chemical formulae using MathJax]({{%relref "shortcodes/math" %}}) + - [Mermaid diagrams for flowcharts, sequences, gantts, pie, etc.]({{%relref "shortcodes/mermaid" %}}) + - [Colorful boxes]({{%relref "shortcodes/notice" %}}) + - [Reveal you site's configuration parameter]({{%relref "shortcodes/siteparam" %}}) + - [Swagger UI for your OpenAPI Specifications]({{%relref "shortcodes/swagger" %}}) + - [Tabbed panels]({{%relref "shortcodes/tabs" %}}) -- Usable offline, no external dependencies -- Usable without a HTTP server from the file system -- Support for Internet Explorer 11 -- Responsive design -- Configurable hidden pages -- Automatic next/prev buttons to navigate through menu entries -- [Automatic Search]({{%relref "basics/configuration#activate-search" %}}) -- [Dedicated search page]({{%relref "basics/configuration#activate-dedicated-search-page" %}}) -- [Support for GFM]({{% relref "cont/markdown" %}}) (GitHub Flavored Markdown) -- [Print]({{%relref "basics/configuration#activate-print-support" %}}) whole chapters or even the complete site -- [Multilingual mode]({{%relref "cont/i18n" %}}) for English, Arabic, Simplified Chinese, Traditional Chinese, Czech, Dutch, Finnish, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese -- Full support for languages written right to left -- [Unrestricted menu configuration]({{%relref "cont/menushortcuts" %}}) relating to amount of items and level of nesting -- [Font Awesome icons]({{%relref "shortcodes/icon" %}}) -- [Tagging support]({{%relref "cont/tags" %}}) -- [Image styling]({{%relref "cont/markdown#images" %}}) like sizing, shadow, border and alignment -- [Syntax highlighting]({{%relref "cont/syntaxhighlight" %}}) -- [Customizable look and feel]({{%relref "basics/customization"%}}) -- [Predefined (light, dark) and customizable color variants]({{%relref "basics/generator" %}}) -- [Automatic switch for light/dark mode]({{%relref "basics/customization/#adjust-to-os-settings" %}}) dependend on your OS settings -- [Attachments files]({{%relref "shortcodes/attachments" %}}) -- [List child pages]({{%relref "shortcodes/children" %}}) -- [Math and chemical formulae]({{%relref "shortcodes/math" %}}) using the MathJax library -- [Mermaid diagrams]({{%relref "shortcodes/mermaid" %}}) for flowcharts, sequences, gantts, pie, etc. -- [Swagger UI]({{%relref "shortcodes/swagger" %}}) for OpenAPI Specifications -- [Badges]({{%relref "shortcodes/badge" %}}) -- [Buttons]({{%relref "shortcodes/button" %}}) -- [Tip/Note/Info/Warning boxes]({{%relref "shortcodes/notice" %}}) -- [Expand]({{%relref "shortcodes/expand" %}}) -- [Tabs]({{%relref "shortcodes/tabs" %}}) -- [File inclusion]({{%relref "shortcodes/include" %}}) - -## Getting Support +## Support To get support, feel free to open a new [discussion topic](https://github.com/McShelby/hugo-theme-relearn/discussions) or [issue report](https://github.com/McShelby/hugo-theme-relearn/issues) in the official repository on GitHub. -## Become a Contributor +## Contributions -Feel free to update this documentation by just clicking the {{% button style="transparent" icon="pen" %}}{{% /button %}} button displayed on top right of each page. Your changes will be deployed automatically once they were reviewed. +Feel free to contribute to this documentation by just clicking the {{% button style="transparent" icon="pen" %}}{{% /button %}} button displayed on top right of each page. Your changes will be deployed automatically once they were reviewed. This requires a GitHub account. -You are most welcome to contribute bugfixes or even new features to the source code by making pull requests to the [official repository](https://github.com/McShelby/hugo-theme-relearn) via GitHub. Please visit the [contribution guidelines]({{%relref "dev/contributing" %}}) first. +You are most welcome to contribute bugfixes or even new features to the source code by making pull requests to the [official repository](https://github.com/McShelby/hugo-theme-relearn) via GitHub. Check the Please [contribution guidelines]({{%relref "dev/contributing" %}}) first before making any changes. ## License -This theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE). +The Relearn theme is licensed under the [MIT License](https://github.com/McShelby/hugo-theme-relearn/blob/main/LICENSE). ## Credits -This theme would not be possible without the work of many others. See the [credits]({{%relref "more/credits" %}}) for a detailed list. +This theme would not be possible without the work of [many others]({{%relref "more/credits" %}}).