Merge pull request #105 from janraasch/feature/extlink-documented

documented external links usage, added icon

README.md

@@ -1,74 +1,56 @@
-# Hugo Scroll ![Test](https://github.com/janraasch/hugo-scroll/workflows/CI/badge.svg?branch=master&event=push)
+# Hugo Scroll
+A [Hugo](https://gohugo.io/) theme for pretty, quick and simple single-page websites.
 
-📜 A [Hugo](https://gohugo.io/)-theme for pretty, quick and simple single-page websites.
+For live demo of master branch, please visit https://janraasch.github.io/hugo-scroll/.
+![Test](https://github.com/janraasch/hugo-scroll/workflows/CI/badge.svg?branch=master&event=push)
 
-![Screenshot Hugo Scroll Theme](https://raw.githubusercontent.com/janraasch/hugo-scroll/master/images/tn.png)
+As a fallback, see a screenshot which may be a bit outdated: ![Screenshot Hugo Scroll Theme](https://raw.githubusercontent.com/janraasch/hugo-scroll/master/images/tn.png)
-
-## Demo
-
-For a current & working demo of this theme please check out https://janraasch.github.io/hugo-scroll/ 🎯.
 
 ## Installation
-
 If you already have a hugo site on your machine, you can simply add this theme via
-
 ```
 git submodule add https://github.com/janraasch/hugo-scroll.git themes/hugo-scroll
 ```
-
 Then, adjust the `config.toml` as detailed below.
 
 If you simply want to check out the `exampleSite`, you can run
-
 ```
 git clone https://github.com/janraasch/hugo-scroll.git hugo-scroll
 cd hugo-scroll
 hugo server --source=exampleSite --themesDir=../..
 ```
 
-For more information read the official [setup guide][hugo-setup-guide] of Hugo.
+For more information, read the official [Hugo setup guide][hugo-setup-guide].
-
-## Adjust configuration / config.toml
-
-Please check out the [config.toml](https://github.com/janraasch/hugo-scroll/blob/master/exampleSite/config.toml) included on the [exampleSite](https://github.com/janraasch/hugo-scroll/tree/master/exampleSite) of this theme.
-
-## Content & structure
-
-### Starting fresh
 
 If you are starting fresh, simply copy over the contents of the `exampleSite`-directory included in this theme to your source directory. That should give you a good idea about how things work, and then you can go on from there to make the site your own.
 
-### Adding content
+Please check out the [config.toml](https://github.com/janraasch/hugo-scroll/blob/master/exampleSite/config.toml) included on the [exampleSite](https://github.com/janraasch/hugo-scroll/tree/master/exampleSite) of this theme.
 
-You can add **a new section to the homepage** via running
+You can add **a new section to the homepage** by running `hugo new homepage/my-new-content.md` (or craft the file manually)
 
-```
+To create **a page separate from the homepage**, run `hugo new my-new-page.md`
-hugo new homepage/my-new-content.md
-```
-
-To create **a page separate from the homepage**, run
-
-```
-hugo new my-new-page.md
-```
-
-### Using icons
-
-This theme includes the full set of [Fork Awesome 1.1.7 Icons][fork-awesome-icons]. Use the `{{<icon>}}`-[shortcode][hugo-shortcodes] with the respective "fa fa-ICONNAME"-`class` to use an icon directly in your `.markdown` files à la
 
+## Features
+### Icons
+This theme includes the full set of [Fork Awesome 1.2.0 Icons][fork-awesome-icons]. Use the `{{<icon>}}`-[shortcode][hugo-shortcodes] with the respective "fa fa-ICONNAME"-`class` to use an icon directly in your `.markdown` files à la
 ```markdown
-Look at this nice »envelope«-icon: {{<icon class="fa fa-envelope">}}. I took this from https://forkaweso.me/Fork-Awesome/icon/envelope/ :-)
+Look at this nice »envelope«-icon: `{{<icon class="fa fa-envelope">}}`. I took this from https://forkaweso.me/Fork-Awesome/icon/envelope/ :-)
 ```
 
-For the full list of icons, see [Fork Awesome 1.1.7 Icons][fork-awesome-icons].
+### External links
+You can add external link in the menu, see `external.md` in the `exampleSite`.
 
-### Adding your branding / colors / css
+You can also use `extlink` shortcode to create a link opening in new tab:
+```markdown
+Visit as at {{<extlink text="Instagram" href="https://www.instagram.com/yourInstagramName/">}}
+```
 
+### Customizing CSS
 Add a `custom_head.html`-file to your `layouts/partials`-directory. In there you may add a `<style>`-tag _or_ you may add a `<link>`-tag referencing your own `custom.css` (in case you prefer to have a separate `.css`-file). Checkout the [`custom_head.html`](https://github.com/janraasch/hugo-scroll/blob/master/exampleSite/layouts/partials/custom_head.html)-file from the `exampleSite`-directory to get started and to find more detailed instructions.
 
 ## Issues / Feedback / Contributing
-
+Please use [GitHub issues](https://github.com/janraasch/hugo-scroll/issues) and [Pull Requests](https://github.com/janraasch/hugo-scroll/pulls). 
-Please use [GitHub issues](https://github.com/janraasch/hugo-scroll/issues) and [Pull Requests](https://github.com/janraasch/hugo-scroll/pulls).
+See [contributing guideline](https://github.com/janraasch/hugo-scroll/blob/master/contributing.md) for more. 
 
 If you do not have a GitHub-account, feel free to hit me up via e-mail (see [janraasch.com](https://www.janraasch.com)).
 
@@ -78,10 +60,8 @@ If you do not have a GitHub-account, feel free to hit me up via e-mail (see [jan
 - Go to [Pexels](https://www.pexels.com), for supplying those wonderful _free_ stock photos on the [exampleSite](https://github.com/janraasch/hugo-scroll/tree/master/exampleSite).
 
 ## License
-
 [MIT License](http://en.wikipedia.org/wiki/MIT_License) © [Jan Raasch](https://www.janraasch.com)
 
 [hugo-setup-guide]: https://gohugo.io/getting-started/installing
-[fork-awesome]: https://forkaweso.me/Fork-Awesome/
 [fork-awesome-icons]: https://forkaweso.me/Fork-Awesome/icons/
 [hugo-shortcodes]: https://gohugo.io/content-management/shortcodes/

contributing.md

@@ -0,0 +1,9 @@
+## [Pull Requests](https://github.com/janraasch/hugo-scroll/pulls)
+We're open to contributions by opening a pull request.
+
+When adding a new feature, please modify also `exampleSite` with an example of how the feature can be activated, configured and used.
+
+Mention new feature also in relevant `readme.md` section.
+
+## [GitHub issues](https://github.com/janraasch/hugo-scroll/issues)
+Used for tracking more complex topics and features.

exampleSite/content/homepage/external.md

@@ -0,0 +1,6 @@
+---
+title: "GitHub"
+weight: 99
+header_menu: true
+external: https://github.com/
+---

layouts/index.html

@@ -12,9 +12,9 @@
             {{ with .Params.header_subheadline }}<h2 class="blog-description">{{ . }}</h2>{{ end }}
 
             {{ range where $sections ".Params.header_menu" "eq" true }}
-	      {{ if isset .Params "external" }}
+              {{ if isset .Params "external" }}
-	         <a class='btn site-menu' href='{{ .Params.external  }}'>{{ .Title }}</a>
+                 <a class='btn site-menu' href='{{ .Params.external  }}'>{{ .Title }} <icon class="fa fa-external-link"></icon></a>
-	      {{ else }}
+              {{ else }}
                  <a class='btn site-menu' data-title-anchor='{{ anchorize .Title }}'>{{ .Title }}</a>
               {{ end }}
             {{ end }}