Merge pull request #123 from plusserver/housekeeping/guidelines-for-i…

…mages

Modify image guidelines

guidelines/20-styling.md

@@ -7,6 +7,7 @@ The purpose of these styling and formatting guidelines is to establish consisten
 ## Structure Guidelines
 
 Every project-structure follows the following rules:
+
 - Use the default folder structure:
   - 01-introduction
   - 02-reference
@@ -18,7 +19,7 @@ Every project-structure follows the following rules:
 
 Every Document must contain the following header:
 
-```
+```markdown
 ---
 title: "TITLE"
 linkTitle: "Link Title"
@@ -82,4 +83,4 @@ This is a primary.
 
 {{% pageinfo color="primary" %}}
 This is placeholder content.
-{{% /pageinfo %}}
+{{% /pageinfo %}}

guidelines/30-markdown.md

@@ -2,21 +2,22 @@
 
 ## Headers
 
-```
+```markdown
 # H1
 ## H2
 ### H3
 ```
 
 ## Emphasis
 
-```
+```markdown
 *This text will be italic*
 **This text will be bold**
 ```
+
 ## Lists
 
-```
+```markdown
 Unordered
 * Item 1
 * Item 2
@@ -28,21 +29,42 @@ Ordered
 
 ## Links
 
-```
+```markdown
 [Link text](https://link.to/url)
 ```
 
 ## Images
 
+You can specify an image using the standard markdown syntax for images:
+
+```markdown
+![Image description](path/to/image)
+```
+
+However, we recommend to use one of the image shortcodes available:
+
+```markdown
+{{< screenshot src="image.png" title="Headline for Image" >}}
+Description of image with **markdown** __support__.
+Placed between title and image.
+{{< /screenshot >}}
 ```
-![Image description](path/to/image || base64)
+
+or
+
+```markdown
+{{< img src="image.png" alt="Short Description of image shown as alt text or when hovering" >}}
 ```
 
-Please use the in-document-base64 style.
+The `image.png` is an example of an image file in your page bundle.
+To create a page bundle, you just create a folder with a `_index.md` file inside.
+The image path is relative to the folder containing the `_index.md` file.
+Do not forget to add the frontmatter to the `_index.md` file.
+If the image is not found, you will get a nil pointer exception when trying to build the site using `hugo --minify`.
 
 ## Code Blocks
 
-```
+```markdown
 # ```javascript
 # var s = "JavaScript syntax highlighting";
 # alert(s);
@@ -55,15 +77,15 @@ Please use codeblock with the matching lanaguage highlighter.
 
 ### Info
 
-```
+```markdown
 {{% alert title="Info" %}}
 This is a info.
 {{% /alert %}}
 ```
 
 ### Alert
 
-```
+```markdown
 {{% alert title="Warning" color="warning" %}}
 This is a warning.
 {{% /alert %}}

layouts/shortcodes/img.html

@@ -0,0 +1,49 @@
+{{/* get file that matches the filename as specified as src="" in shortcode */}}
+{{ $src := .Page.Resources.GetMatch (printf "*%s*" (.Get "src")) }}
+
+{{/* set image sizes, these are hardcoded for now, x dictates that images are resized to this width */}}
+
+{{ $tinyw := default "500x" }}
+{{ $smallw := default "800x" }}
+{{ $mediumw := default "1200x" }}
+{{ $largew := default "1500x" }}
+
+{{/* resize the src image to the given sizes */}}
+
+{{ .Scratch.Set "tiny" ($src.Resize $tinyw) }}
+{{ .Scratch.Set "small" ($src.Resize $smallw) }}
+{{ .Scratch.Set "medium" ($src.Resize $mediumw) }}
+{{ .Scratch.Set "large" ($src.Resize $largew) }}
+
+{{/* add the processed images to the scratch */}}
+
+{{ $tiny := .Scratch.Get "tiny" }}
+{{ $small := .Scratch.Get "small" }}
+{{ $medium := .Scratch.Get "medium" }}
+{{ $large := .Scratch.Get "large" }}
+
+{{/* only use images smaller than or equal to the src (original) image size, as Hugo will upscale small images */}}
+{{/* set the sizes attribute to (min-width: 35em) 1200px, 100vw unless overridden in shortcode */}}
+
+<img 
+  {{ with .Get "sizes" }}sizes='{{.}}'{{ else }}sizes="(min-width: 35em) 1200px, 100vw"{{ end }}
+  srcset='
+  {{ if ge $src.Width "500" }}
+    {{ with $tiny.RelPermalink }}{{.}} 500w{{ end }}
+  {{ end }}
+  {{ if ge $src.Width "800" }}
+    {{ with $small.RelPermalink }}, {{.}} 800w{{ end }}
+  {{ end }}
+  {{ if ge $src.Width "1200" }}
+    {{ with $medium.RelPermalink }}, {{.}} 1200w{{ end }}
+  {{ end }}
+  {{ if ge $src.Width "1500" }}
+    {{ with $large.RelPermalink }}, {{.}} 1500w {{ end }}
+  {{ end }}'
+  {{ if .Get (print $medium) }}
+    src="{{ $medium.RelPermalink }}" 
+  {{ else }}
+    src="{{ $src.RelPermalink }}" 
+  {{ end }}
+  {{ with .Get "alt" }}alt="{{.}}" title="{{.}}"{{ end }}
+>