diff --git a/.dictionary b/.dictionary index 227f2b4..6fce13a 100644 --- a/.dictionary +++ b/.dictionary @@ -7,3 +7,6 @@ ToC macOS SVG HC-primary +pre-processor +pre-build +submodule diff --git a/README.md b/README.md index 594eaed..7bc70cd 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,28 @@ [![Hugo Version](https://img.shields.io/badge/hugo-0.65-blue.svg)](https://gohugo.io) [![GitHub release](https://img.shields.io/github/v/release/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/releases/latest) [![GitHub contributors](https://img.shields.io/github/contributors/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/graphs/contributors) -[![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekdoc)](LICENSE) +[![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/blob/master/LICENSE) Geekdoc is a simple Hugo theme for documentations. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there. You can find a demo and the full documentation at [https://geekdocs.de](https://geekdocs.de). ![Desktop and mobile preview](https://github.com/xoxys/hugo-geekdoc/blob/master/images/readme.png) +## Build and release process + +This theme is subject to a CI driven build and release process common for software development. During the release build, all necessary assets are automatically built by [gulp](https://gulpjs.com/) and bundled in a release tarball. You can download the latest release from the [GitHub release page](https://github.com/xoxys/hugo-geekdoc/releases). + +Due to the fact that `gulp` is used as pre-processor the theme cannot be used from the master branch by default. If you want to use the theme from a cloned branch instead of a release tarball you'll need to install `gulp` locally and run the default pipeline once to create all required assets. + +```Shell +# install required packages from package.json +npm install + +# run gulp pipeline to build required assets +gulp default +``` + +See the [Getting Started Guide](https://geekdocs.de/usage/getting_started/) for details about the different setup options. + ## Contributors Special thanks goes to all [contributors](https://github.com/xoxys/hugo-geekdoc/graphs/contributors). diff --git a/exampleSite/config.yaml b/exampleSite/config.yaml index 89d88f1..b6771ae 100644 --- a/exampleSite/config.yaml +++ b/exampleSite/config.yaml @@ -9,7 +9,7 @@ pygmentsCodeFences: true disablePathToLower: true enableGitInfo: true -# Needed for mermaid/katex shortcodes +# Needed for mermaid shortcodes markup: goldmark: renderer: diff --git a/exampleSite/content/_index.md b/exampleSite/content/_index.md index d41f732..324469b 100644 --- a/exampleSite/content/_index.md +++ b/exampleSite/content/_index.md @@ -5,9 +5,10 @@ title: Documentation [![Build Status](https://img.shields.io/drone/build/xoxys/hugo-geekdoc?logo=drone)](https://cloud.drone.io/xoxys/hugo-geekdoc) [![Hugo Version](https://img.shields.io/badge/hugo-0.65-blue.svg)](https://gohugo.io) [![GitHub release](https://img.shields.io/github/v/release/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/releases/latest) +[![GitHub contributors](https://img.shields.io/github/contributors/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/graphs/contributors) [![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/blob/master/LICENSE) -Geekdoc is a simple Hugo theme for documentations. This work is inspired and partially based on the [hugo-book](https://github.com/alex-shpak/hugo-book) theme. +Geekdoc is a simple Hugo theme for documentations. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there. You can find a demo and the full documentation at [https://geekdocs.de](https://geekdocs.de). ## Features diff --git a/exampleSite/content/usage/_index.md b/exampleSite/content/usage/_index.md index 6486c07..eab4aee 100644 --- a/exampleSite/content/usage/_index.md +++ b/exampleSite/content/usage/_index.md @@ -1,3 +1,4 @@ --- title: Usage +weight: -10 --- diff --git a/exampleSite/content/usage/configuration.md b/exampleSite/content/usage/configuration.md index 110da61..3dfc95e 100644 --- a/exampleSite/content/usage/configuration.md +++ b/exampleSite/content/usage/configuration.md @@ -1,3 +1,8 @@ +--- +title: Configuration +weight: -10 +--- + ## Site configuration {{< tabs "site-config" >}} diff --git a/exampleSite/content/usage/getting_started.md b/exampleSite/content/usage/getting_started.md new file mode 100644 index 0000000..4f5b910 --- /dev/null +++ b/exampleSite/content/usage/getting_started.md @@ -0,0 +1,103 @@ +--- +title: Getting Started +weight: -20 +--- + +This page tells you how to get started with the Geekdoc theme, including installation and basic configuration. + + + +{{< toc >}} + + + +## Install requirements + +You need a recent version of Hugo for local builds and previews of sites that use Geekdoc. As we are using [gulp](https://gulpjs.com/) as pre-processor the normal version of Hugo is sufficient. If you prefer the extended version of Hugo anyway this will work as well. For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/documentation/). + +If you want to use the theme from a cloned branch instead of a release tarball you'll need to install `gulp` locally and run the default pipeline once to create all required assets. + +```Shell +# install required packages from package.json +npm install + +# run gulp pipeline to build required assets +gulp default +``` + +## Using the theme + +To prepare your new site environment just a few steps are required: + +1. Create a new empty Hugo site. + + ```Shell + hugo new site demosite + ``` + +2. Switch to the root of the new site. + + ```Shell + cd demosite + ``` + +3. Install the Geekdoc theme from a [release bundle](#option-1-download-pre-build-release) (recommended) or form [Git branch](#option-2-clone-the-github-repository). + +4. Create the minimal required Hugo configuration `config.toml`. For all configuration options see [here](/usage/configuration/). + + ```Toml + baseURL = "http://localhost" + title = "Geekdocs" + theme = "hugo-geekdoc" + + # Geekdoc required configuration + pygmentsUseClasses = true + pygmentsCodeFences = true + + disablePathToLower = true + enableGitInfo=true + + # Needed for mermaid shortcodes + [markup] + [markup.goldmark.renderer] + # Needed for mermaid shortcode + unsafe = true + [markup.tableOfContents] + startLevel = 1 + endLevel = 9 + ``` + +5. Test your site. + + ```Shell + hugo server --theme geekdoc -D + ``` + +### Option 1: Download pre-build release bundle + +Download and extract the latest release bundle into the theme directory. + +```Shell +curl -L https://github.com/xoxys/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1 +``` + +### Option 2: Clone the GitHub repository + +{{< hint info >}} +**Info**\ +Keep in mind this method is not recommended and needs some extra steps to get it working. +If you want to use the Theme as submodule keep in mind that your build process need to +run the described steps as well. +{{< /hint >}} + +Clone the Geekdoc git repository. + +```Shell +git clone https://github.com/xoxys/hugo-geekdoc.git themes/geekdoc +``` + +Build required theme assets e.g. CSS files and SVG sprites with `gulp`. + +```Shell +gulp default +``` diff --git a/package-lock.json b/package-lock.json index 4061ef1..fcfdce4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -5235,6 +5235,18 @@ "integrity": "sha512-LmeoohTpp/K4UiyQCwuGWlONxXamGzCMtFxLq4W1nZVGIQLYvMCJx3yAF9qyyuFpflABI9yVdtJAqbihOsCsJQ==", "dev": true }, + "prettier": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.1.1.tgz", + "integrity": "sha512-9bY+5ZWCfqj3ghYBLxApy2zf6m+NJo5GzmLTpr9FsApsfjriNnS2dahWReHMi7qNPhhHl9SYHJs2cHZLgexNIw==", + "dev": true + }, + "prettier-plugin-go-template": { + "version": "0.0.10", + "resolved": "https://registry.npmjs.org/prettier-plugin-go-template/-/prettier-plugin-go-template-0.0.10.tgz", + "integrity": "sha512-TaHPqiMK/zfk+YhvKRf/1WZDgQ6ffnlxJZX5rwphqfxBOVEezZQtYistTB348MKrKnnwKpyXZWpMRo0/KCVB+A==", + "dev": true + }, "pretty-hrtime": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz", diff --git a/package.json b/package.json index 818b552..84a04f3 100644 --- a/package.json +++ b/package.json @@ -23,6 +23,8 @@ "gulp-rename": "^2.0.0", "gulp-sass": "^4.1.0", "gulp-svg-sprite": "^1.5.0", + "prettier": "^2.1.1", + "prettier-plugin-go-template": "0.0.10", "run-sequence": "^2.2.1" }, "browserslist": [