diff --git a/_includes/image.html b/_includes/image.html new file mode 100644 index 0000000..6aaa9c0 --- /dev/null +++ b/_includes/image.html @@ -0,0 +1 @@ +
{% if {{include.url}} %}{% endif %}{{include.alt}}{% if {{include.url}} %}{% endif %}{% if {{include.caption}} %}
{{include.caption}}
{% endif %} diff --git a/_includes/inline_image.html b/_includes/inline_image.html new file mode 100644 index 0000000..3725f8a --- /dev/null +++ b/_includes/inline_image.html @@ -0,0 +1 @@ +{{include.alt}} diff --git a/css/customstyles.css b/css/customstyles.css index 4f659d5..4c6654e 100644 --- a/css/customstyles.css +++ b/css/customstyles.css @@ -935,7 +935,8 @@ a[href^="http://"]:after, a[href^="https://"]:after { /* Strip the outbound icon when this class is present */ a[href].noCrossRef::after, -a.no_icon:after { +a.no_icon:after + { content:"" !important; padding-left: 0; } @@ -1136,3 +1137,20 @@ div.box.box1 { word-wrap: break-word; /* Internet Explorer 5.5+ */ font-size: 14px; } + +/* + * Let's target IE to respect aspect ratios and sizes for img tags containing SVG files + * + * [1] IE9 + * [2] IE10+ + */ +/* 1 */ +.ie9 img[src$=".svg"] { + width: 100%; +} +/* 2 */ +@media screen and (-ms-high-contrast: active), (-ms-high-contrast: none) { + img[src$=".svg"] { + width: 100%; + } +} diff --git a/mydoc/mydoc_alerts.md b/mydoc/mydoc_alerts.md index afcb748..6896116 100644 --- a/mydoc/mydoc_alerts.md +++ b/mydoc/mydoc_alerts.md @@ -13,29 +13,35 @@ Alerts are little warnings, info, or other messages that you have called out in ## Alerts -You can insert an alert by using any of the following code. +Similar to [inserting images]({{site.data.urls.mydoc_images.url}}), you insert alerts through various includes that have been developed. These includes provide templates through which you pass parameters to easily populate the right HTML code. ``` {%raw%}{% include note.html content="This is my note. All the content I type here is treated as a single paragraph." %}{% endraw%} ``` -Here's the result: +Here's the result: {% include note.html content="This is my note. All the content I type here is treated as a single paragraph." %} -If you need multiple paragraphs, enter `

` tags, like this: +With alerts, there's just one include property: + +| Property | description | +|-------|--------| +| content | The content for the alert. | + +If you need multiple paragraphs, enter `

` tags. This is because block level tags aren't allowed here, as Kramdown is processing the content as Markdown despite the fact that the content is surrounded by HTML tags. Here's an example with a break: ``` {%raw%}{% include note.html content="This is my note. All the content I type here is treated as a single paragraph.

Now I'm typing on a new line." %}{% endraw%} ``` -Here's the result: +Here's the result: {% include note.html content="This is my note. All the content I type here is treated as a single paragraph.

Now I'm typing on a new line." %} ## Types of alerts available -There are four types of alerts you can leverage: +There are four types of alerts you can leverage: * note.html * tip.html @@ -52,10 +58,8 @@ They function the same except they have a different color, icon, and alert word. {% include important.html content="This is my important info." %} - These alerts leverage includes stored in the \_include folder. The `content` option is a parameter that you pass to the include. In the include, the parameter is passed like this: - ``` {% raw %} ``` @@ -66,7 +70,7 @@ The content in `content="This is my note."` gets inserted into the `{% raw %}{{i There's another type of callout available called callouts. This format is typically used for longer callout that spans mreo than one or two paragraphs, but really it's just a stylistic preference whether to use an alert or callout. -Here's the syntax for a callout: +Here's the syntax for a callout: ``` {% raw %}{% include callout.html content="This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs. " type="primary" %} {% endraw %} @@ -76,46 +80,44 @@ Here's the result: {% include callout.html content="This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs." type="primary" %} -To include paragraph breaks, use `

` inside the callout: +The available properties for callouts are as follows: + +| Property | description | +|-------|--------| +| content | The content for the callout. | +| type | The style for the callout. Options are `danger`, `default`, `primary`, `success`, `info`, and `warning`.| + +The types just define the color of the left border. Each of these callout types get inserted as a class name in the callout template. These class names correspond with styles in Bootstrap. These classes are common Bootstrap class names whose style attributes differ depending on your Bootstrap theme and style definitions. + +Here's an example of each different type of callout: + +{% include callout.html content="This is my **danger** type callout. It has a border on the left whose color you define by passing a type parameter." type="danger" %} + +{% include callout.html content="This is my **default** type callout. It has a border on the left whose color you define by passing a type parameter." type="default" %} + +{% include callout.html content="This is my **primary** type callout. It has a border on the left whose color you define by passing a type parameter." type="primary" %} + +{% include callout.html content="This is my **success** type callout. It has a border on the left whose color you define by passing a type parameter." type="success" %} + +{% include callout.html content="This is my **info** type callout. It has a border on the left whose color you define by passing a type parameter." type="info" %} + +{% include callout.html content="This is my **warning** type callout. It has a border on the left whose color you define by passing a type parameter." type="warning" %} + +Now that in contrast to alerts, callouts don't include the alert word (note, tip, warning, or important). + +To include paragraph breaks, use `

` inside the callout: ``` {% raw %}{% include callout.html content="**Important information**: This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs.

Here I am starting a new paragraph, because I have lots of information to share. You may wonder why I'm using line breaks instead of paragraph tags. This is because Kramdown processes the Markdown here as a span rather than a div (for whatever reason). Be grateful that you can be using Markdown at all inside of HTML. That's usually not allowed in Markdown syntax, but it's allowed here." type="primary" %} {% endraw %} ``` -Here's the result: +Here's the result: {% include callout.html content="**Important information**: This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs.

Here I am starting a new paragraph, because I have lots of information to share. You may wonder why I'm using line breaks instead of paragraph tags. This is because Kramdown processes the Markdown here as a span rather than a div (for whatever reason). Be grateful that you can be using Markdown at all inside of HTML. That's usually not allowed in Markdown syntax, but it's allowed here." type="primary" %} -The type options are as follows: - -* `danger` -* `default` -* `primary` -* `success` -* `info` -* `warning` - -These types just define the color of the left border. Each of these callout types get inserted as a class name in the callout template. These class names correspond with styles in Bootstrap. These classes are common Bootstrap class names whose style attributes differ depending on your Bootstrap theme and style definitions. - -Here's an example of each different type of callout: - -{% include callout.html content="This is my **danger** type callout. It has a border on the left whose color you define by passing a type parameter." type="danger" %} - -{% include callout.html content="This is my **default** type callout. It has a border on the left whose color you define by passing a type parameter." type="default" %} - -{% include callout.html content="This is my **primary** type callout. It has a border on the left whose color you define by passing a type parameter." type="primary" %} - -{% include callout.html content="This is my **success** type callout. It has a border on the left whose color you define by passing a type parameter." type="success" %} - -{% include callout.html content="This is my **info** type callout. It has a border on the left whose color you define by passing a type parameter." type="info" %} - -{% include callout.html content="This is my **warning** type callout. It has a border on the left whose color you define by passing a type parameter." type="warning" %} - -Now that in contrast to alerts, callouts don't include the alert word (note, tip, warning, or important). - ## Markdown inside of callouts and alerts -You can use Markdown inside of callouts and alerts, even though this content actually gets inserted inside of HTML in the include. This is one of the advantages of Kramdown Markdown. The include template has an attribute of `markdown="span"` that allows for the processer to parse Markdown inside of HTML. +You can use Markdown inside of callouts and alerts, even though this content actually gets inserted inside of HTML in the include. This is one of the advantages of kramdown Markdown. The include template has an attribute of `markdown="span"` that allows for the processor to parse Markdown inside of HTML. ## Validity checking @@ -124,7 +126,7 @@ If you have some of the syntax wrong with an alert or callout, you'll see an err ``` {% raw %}Liquid Exception: Invalid syntax for include tag: content="This is my **info** type callout. It has a border on the left whose color you define by passing a type parameter. type="info" Valid syntax: {% include file.ext param='value' param2='value' %} in mydoc/mydoc_alerts.md {% endraw %} ``` - + These errors are a good thing, because it lets you know there's an error in your syntax. Without the errors, you may not realize that you coded something incorrectly until you see the lack of alert or callout styling in your output. In this case, the quotation marks aren't set correctly. I forgot the closing quotation mark for the content parameter include. @@ -132,4 +134,3 @@ In this case, the quotation marks aren't set correctly. I forgot the closing quo ## Blast a warning to users on every page If you want to blast a warning to users on every page, add the alert or callout to the \_layouts/page.html page right below the frontmatter. Every page using the page layout (all, by defaut) will show this message. - diff --git a/mydoc/mydoc_images.md b/mydoc/mydoc_images.md index 877141b..3fe0814 100644 --- a/mydoc/mydoc_images.md +++ b/mydoc/mydoc_images.md @@ -3,93 +3,73 @@ title: Images tags: [formatting] keywords: images, screenshots, vectors, svg, markdown syntax last_updated: March 20, 2016 -summary: "You embed images using traditional HTML or Markdown syntax for images. Unlike pages, you can store images in subfolders (in this theme). This is because when pages reference the images, the references are always as subpaths, never requiring the reference to move up directories." +summary: "Store images in the images folder and use the image.html include to insert images. This include has several options, including figcaptions, that extract the content from the formatting." sidebar: mydoc_sidebar permalink: /mydoc_images/ --- -You embed an image the same way you embed other files or assets: you put the file into a folder, and then link to that file. +## Image Include Template -Put images inside the `images` folder in your root directory. You can create subdirectories inside this directory. Although you could use Markdown syntax for images, the HTML syntax is probably easier: +Instead of using Markdown or HMTL syntax directly in your page for images, the syntax for images has been extracted out into an image include that allows you to pass the parameters you need. Include the image.html like this: +```liquid {% raw %} -```html - -``` +{% include image.html file="jekyll.png" url="http://jekyllrb.com" alt="Jekyll" caption="This is a sample caption" %"} {% endraw %} - -And the result: - - - -Here's the same Markdown syntax: - -{% raw %} ``` -![My sample page]({{ "/images/jekyll.png" | prepend: site.baseurl }}) -``` -{% endraw %} -And the result: +The available include properties are as follows: -![My sample page]({{ "/images/jekyll.png" | prepend: site.baseurl }}) +| Property | description | +|-------|--------| +| file | The name of the file. Store it in the /images folder. | +| url | Whether to link the image to a URL | +| alt | Alternative image text for accessibility and SEO | +| caption | A caption for the image | +| max-width | a maximum width for the image (in pixels). Just specify the number, not px.| -{{site.data.alerts.tip}} I recommend storing this format into a shortcut editor such as aText. This way when you want to insert an image, just type something like jimg and the shortcut editor will automatically type the code.{{site.data.alerts.end}} - -## Figure captions - -If you want to add a figure caption, you can do so using standard `figure` HTML tags: - -{% raw %} -```html -
Your caption
-``` -{% endraw %} +The properties of the include get populated into the image.html template. Here's the result: - -
Your caption
+{% include image.html file="jekyll.png" url="http://jekyllrb.com" alt="Jekyll" caption="This is a sample caption" %} ## SVG Images You can also embed SVG graphics. If you use SVG, you need to use the HTML syntax so that you can define a width/container for the graphic. Here's a sample embed: -```html - +```liquid +{% raw %}{% include image.html file="helpapi.svg" url="http://idratherbewriting.com/documentation-theme-jekyll/mydoc_help_api/" alt="Building a Help API" caption="A help API provides a JSON file at a web URL with content that can be pulled into different targets" max-width="600" %}{% endraw %} ``` Here's the result: - -SVG images will expand to the size of their container, so you have to specify it here. The previous syntax isn't well supported in IE, so you would be better off using the `object` element like this: +{% include image.html file="helpapi.svg" url="http://idratherbewriting.com/documentation-theme-jekyll/mydoc_help_api/" alt="Building a Help API" caption="A help API provides a JSON file at a web URL with content that can be pulled into different targets" max-width="600" %} -{% raw %} -```html -
Your browser does not support SVG -
+The stylesheet even handles SVG display in IE 9 and earlier through the following style (based on this [gist](https://gist.github.com/larrybotha/7881691)): + +```css +/* + * Let's target IE to respect aspect ratios and sizes for img tags containing SVG files + * + * [1] IE9 + * [2] IE10+ + */ +/* 1 */ +.ie9 img[src$=".svg"] { + width: 100%; +} +/* 2 */ +@media screen and (-ms-high-contrast: active), (-ms-high-contrast: none) { + img[src$=".svg"] { + width: 100%; + } +} ``` -{% endraw %} - -Here's the same code with `figure` elements: - -{% raw %} -```html -
Your browser does not support SVG
This is your caption
-
-``` -{% endraw %} - -And the result: - -
Your browser does not support SVG
This is your caption
Also, if you're working with SVG graphics, note that Firefox does not support SVG fonts. In Illustrator, when you do a Save As with your AI file and choose SVG, to preserve your fonts, in the Font section, select "Convert to outline" as the Type (don't choose SVG in the Font section). Also, remove the check box for "Use textpath element for text on a path". And select "Embed" rather than "Link." The following screenshot shows the settings I use. Your graphics will look great in Firefox. ![Essential options for SVG with Illustrator]({{ "/images/illustratoroptions.png" | prepend: site.baseurl }}) - - -