---
title: Alerts
tags: [formatting]
keywords: notes, tips, cautions, warnings, admonitions
last_updated: July 3, 2016
summary: "You can insert notes, tips, warnings, and important alerts in your content. These notes are stored as shortcodes made available through the linksrefs.hmtl include."
-sidebar: mydoc_sidebar
+sidebar: mydoc_sidebar
permalink: mydoc_alerts
---
-```
+
The `sidebar: mydoc_sidebar` refers to the \_data/sidebars/mydoc_sidebar.yml file (meaning, the mydoc_sidebar.yml file inside the sidebars subfolder inside the \data folder).
@@ -102,7 +104,7 @@ If no sidebar assignment is found in the page frontmatter, the default sidebar (
Note that your sidebar can only have 2 levels. Given that each product has its own sidebar, this depth should be sufficient (it's really like 3 levels). Deeper nesting goes against usability recommendations.
-Additionally, each level must have at least one topic before the next level starts. You can't have a second level that contains multiple third levels without having at least one standalone topic in the second level.
+{% include note.html content="Note that each level must have at least one topic before the next level starts. You can't have a second level that contains multiple third levels without having at least one standalone topic in the second level." %}
For more detail on the sidebar, see [Sidebar navigation][mydoc_sidebar_navigation].
@@ -186,9 +188,7 @@ For more detail on the sidebar, see [Sidebar navigation][mydoc_sidebar_navigatio
This theme uses relative links throughout so that you can view the site offline and not worry about which server or directory you're hosting it. It's common with tech docs to push content to an internal server for review prior to pushing the content to an external server for publication. Because of the need for seamless transferrence from one host to another, the site has to use relative links.
-To view pages locally on your machine, they need to have the `.html` extension. However, if you prefer not to have this extension, you can simply remove the `.html` from the sidebar entries, and the pages will still work when you view content on a preview server or web server.
-
-The `permalink` property in the page's frontmatter combined with the `include: ['pages']` property in the configuration file is what pushes the files into the root directory when the site builds.
+To view pages locally on your machine (without the Jekyll preview server), they need to have the `.html` extension. The `permalink` property in the page's frontmatter (without surrounding slashes) is what pushes the files into the root directory when the site builds.
## Page frontmatter
@@ -201,22 +201,22 @@ tags: [sample1, sample2]
keywords: keyword1, keyword2, keyword3
last_updated: Month day, year
summary: "optional summary here"
-sidebar: sidebar name
-permalink: filename
+sidebar: sidebarname
+permalink: filename.html
---
```
(You will customize the values for each of these properties, of course.)
-For titles, surrounding the title in quotes is optional, but if you have a colon in the title, you must surround the title with quotation marks. If you have a quotation mark within the title, escape it first with a backlash `\`.
+For titles, surrounding the title in quotes is optional, but if you have a colon in the title, you must surround the title with quotation marks. If you have a quotation mark inside the title, escape it first with a backlash `\`.
Values for `keywords` get populated into the metadata of the page for SEO.
-Values for `tags` must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.)
+Values for `tags` must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll won't auto-create these tag files.)
If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: false` in the frontmatter.
-The `permalink` value should be the same as your filename but without the file extension.
+The `permalink` value should be the same as your filename and include the ".html" file extension.
For more detail, see [Pages][mydoc_pages].
@@ -232,7 +232,7 @@ For more information, see [Pages][mydoc_pages] and [Posts][mydoc_posts].
The top navigation bar's menu items are set through the \_data/topnav.yml file. Use the top navigation bar to provide links for navigating from one product to another, or to navigate to external resources.
-For external URLs, use `external_url` in the item property, as shown in the example topnav.yml file. For internal links, use `url` as usual.
+For external URLs, use `external_url` in the item property, as shown in the example topnav.yml file. For internal links, use `url` the same was you do in the sidebar data files.
Note that the topnav has two sections: `topnav` and `topnav_dropdowns`. The topnav section contains single links, while the `topnav_dropdowns` section contains dropdown menus. The two sections are independent of each other.
diff --git a/pages/mydoc/mydoc_build_arguments.md b/pages/mydoc/mydoc_build_arguments.md
index 8f1736a5c..6b5593b9b 100644
--- a/pages/mydoc/mydoc_build_arguments.md
+++ b/pages/mydoc/mydoc_build_arguments.md
@@ -63,6 +63,6 @@ kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
I recommend creating a profile in iTerm that stores this command. Here's what the iTerm settings look like:
-![iTerm profile settings to kill all Jekyll]({{ "/images/killalljekyll.png" | prepend: site.baseurl }})
+{% include image.html file="killalljekyll.png" caption="iTerm profile settings to kill all Jekyll" %}
{% include links.html %}
diff --git a/pages/mydoc/mydoc_generating_pdfs.md b/pages/mydoc/mydoc_generating_pdfs.md
index 60776ad5b..c4cbbfb54 100644
--- a/pages/mydoc/mydoc_generating_pdfs.md
+++ b/pages/mydoc/mydoc_generating_pdfs.md
@@ -23,7 +23,7 @@ Also, creating a PDF this way gives you a lot more control and customization cap
You can see an example of the finished product here:
-
+
## 1. Set up Prince
@@ -348,7 +348,7 @@ You can add a download button for your PDF using some Bootstrap button code:
Here's what that looks like:
-
+
## JavaScript conflicts
diff --git a/pages/mydoc/mydoc_help_api.md b/pages/mydoc/mydoc_help_api.md
index 89d4e7d63..e8dfcc57a 100644
--- a/pages/mydoc/mydoc_help_api.md
+++ b/pages/mydoc/mydoc_help_api.md
@@ -13,9 +13,9 @@ folder: mydoc
You can create a help API that developers can use to pull in content.
-For the full code demo, see the notes in the tooltip demo.
+For the full code demo, see the notes in the [Tooltips file](tooltips.html).
-In this demo, the popovers pull in and display content from the information in a tooltips.json file located in the same directory.
+In this demo, the popovers pull in and display content from the information in a tooltips.json file located in the same directory.
Instead of placing the JSON source in the same directory, you could also host the JSON file on another site.
@@ -25,7 +25,7 @@ Additionally, instead of tooltip popovers, you could also print content directly
Here's a diagram showing the basic idea of the help API:
-
Is this really an API? Well, sort of. The help content is pushed out into a JSON file that other websites and applications can easily consume. The endpoints don't deliver different data based on parameters added to a URL. But the overall concept is similar to an API: you have a client requesting resources from a server.
@@ -136,7 +136,7 @@ This code will loop through all pages in the tooltips collection and insert the
}
```
-You can also view the same JSON file here: tooltips.json.
+You can also view the same JSON file here: tooltips.json.
You can add different fields depending on how you want the JSON to be structured. Here we just have to fields: `id` and `body`. And the JSON is looking just in the tooltips collection that we created.
@@ -230,7 +230,7 @@ $.get( url, function( data ) {
{% endraw %}
```
-View the tooltip demo for a demo.
+View the tooltip demo for a demonstration.
The `url` in the demo is relative, but you could equally point it to an absolute path on a remote host assuming CORS is enabled on the host.
@@ -268,7 +268,7 @@ Again, see the Tooltip Demo for a dem
Note that even though you reference a Bootstrap JS script, Bootstrap's popovers require you to initialize them using the above code as well — they aren't turned on by default.
-View the source code of the tooltip demo for the full comments.
+View the source code of the tooltip demo for the full comments.
## 8. Create easy links to embed the help in your help site
diff --git a/pages/mydoc/mydoc_icons.md b/pages/mydoc/mydoc_icons.md
index 18d0fc421..daf76f4e9 100644
--- a/pages/mydoc/mydoc_icons.md
+++ b/pages/mydoc/mydoc_icons.md
@@ -220,6 +220,6 @@ You can use any of the following:
The only difference is the color of the left bar.
-Callouts are explained in a bit more detail in Alerts.
+Callouts are explained in a bit more detail in [Alerts][mydoc_alerts].
{% include links.html %}
diff --git a/pages/mydoc/mydoc_images.md b/pages/mydoc/mydoc_images.md
index b466d64ae..225d722a5 100644
--- a/pages/mydoc/mydoc_images.md
+++ b/pages/mydoc/mydoc_images.md
@@ -92,6 +92,6 @@ Also, if you're working with SVG graphics, note that Firefox does not support SV
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 }})
+{% include image.html file="illustratoroptions.png" caption="Essential options for SVG with Illustrator" %}
{% include links.html %}
diff --git a/pages/mydoc/mydoc_introduction.md b/pages/mydoc/mydoc_introduction.md
index 85a25a2b3..a94409530 100644
--- a/pages/mydoc/mydoc_introduction.md
+++ b/pages/mydoc/mydoc_introduction.md
@@ -25,6 +25,6 @@ Some of the more prominent features of this theme include the following:
## Getting started
-To get started, see [Getting Started][home].
+To get started, see [Getting Started][index].
{% include links.html %}
diff --git a/pages/mydoc/mydoc_iterm_profiles.md b/pages/mydoc/mydoc_iterm_profiles.md
index 2784a665a..5116d30e0 100644
--- a/pages/mydoc/mydoc_iterm_profiles.md
+++ b/pages/mydoc/mydoc_iterm_profiles.md
@@ -31,7 +31,7 @@ When you're working with tech docs, a lot of times you have builds that push fil
Here's an example:
-![iTerm profile example]({{ "/images/itermexample.png" | prepend: site.baseurl }})
+{% include image.html file="itermexample.png" caption="iTerm profile example" %}
## Launching a profile
diff --git a/pages/mydoc/mydoc_kb_layout.md b/pages/mydoc/mydoc_kb_layout.md
index 886833ed5..813e4af05 100644
--- a/pages/mydoc/mydoc_kb_layout.md
+++ b/pages/mydoc/mydoc_kb_layout.md
@@ -27,7 +27,7 @@ Here's the sample knowledge-base style layout:
@@ -42,7 +42,7 @@ Here's the sample knowledge-base style layout:
@@ -57,7 +57,7 @@ Here's the sample knowledge-base style layout:
@@ -72,7 +72,7 @@ Here's the sample knowledge-base style layout:
@@ -90,7 +90,7 @@ If you don't want to link to a tag archive index, but instead want to list all p
{% for page in sorted_pages %}
{% for tag in page.tags %}
{% if tag == "getting_started" %}
-