HPCE/gitea-pages
0
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Activity

updated the way I do callouts and alerts. This approach is better than the old way. You use includes here and pass parameters. This approach leads to fewer errors. The output looks the same, and you can use Markdown directly inside of the alerts or callouts instead of switching to HTML syntax.

Browse Source
This commit is contained in:
tomjohnson1492
2016-04-09 09:18:55 -07:00
parent 8100e01ecf
commit d7d5286239
6 changed files with 197 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
index.md
View File

@ -194,7 +194,7 @@ For blog posts, create your markdown files in the \_posts folder following the s
The news/news.html file displays the posts, and the news_archive.html file shows a yearly history of posts. In documentation, you might use the news to highlight product features outside of your documentation, or to provide release notes and other updates.
See {{site.data.urls.mydoc_posts}} for more information.
See {{site.data.urls.mydoc_posts.link}} for more information.
## Markdown

140
mydoc/mydoc_alerts.md
View File

@ -15,71 +15,121 @@ Alerts are little warnings, info, or other messages that you have called out in
You can insert an alert by using any of the following code.
{%raw%}
alert | code
------|---------
note | {{site.data.alerts.note}} your note {{site.data.alerts.end}}
tip | {{site.data.alerts.tip}} your tip {{site.data.alerts.end}}
warning | {{site.data.alerts.warning}} your warning {{site.data.alerts.end}}
important | {{site.data.alerts.important}} your important info {{site.data.alerts.end}}
{%endraw%}
```
{%raw%}{% include note.html content="This is my note. All the content I type here is treated as a single paragraph." %}{% endraw%}
```
The following demonstrate the formatting associated with each alert.
Here's the result:
{{site.data.alerts.tip}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
{% include note.html content="This is my note. All the content I type here is treated as a single paragraph." %}
{{site.data.alerts.note}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
If you need multiple paragraphs, enter `<br/><br/>` tags, like this:
{{site.data.alerts.important}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
```
{%raw%}{% include note.html content="This is my note. All the content I type here is treated as a single paragraph. <br/><br/> Now I'm typing on a new line." %}{% endraw%}
```
{{site.data.alerts.warning}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
Here's the result:
{% include note.html content="This is my note. All the content I type here is treated as a single paragraph. <br/><br/> Now I'm typing on a new line." %}
## Types of alerts available
There are four types of alerts you can leverage:
* note.html
* tip.html
* warning.html
* important.html
They function the same except they have a different color, icon, and alert word. You include the different types by selecting the include template you want. Here are samples of each alert:
{% include note.html content="This is my note." %}
{% include tip.html content="This is my tip." %}
{% include warning.html content="This is my warning." %}
{% 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 %}<div markdown="span" class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> {{include.content}}{% endraw %}</div>
```
The content in `content="This is my note."` gets inserted into the `{% raw %}{{include.content}}}{% endraw %}` part of the template. You can follow this same pattern to build additional includes. See this [Jekyll screencast on includes](http://jekyll.tips/jekyll-casts/includes/) for more information.
## Callouts
In contrast to the alerts, the callouts don't have a pre-coded bold-formatted preface such as note or tip. You just add one (if desired) in the callout text itself.
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.
{%raw%}
callout | code
------|---------
callout_default | {{site.data.alerts.callout_default}} your callout_default content {{site.data.alerts.end}}
callout_primary | {{site.data.alerts.callout_primary}} your callout_primary content {{site.data.alerts.end}}
callout_success | {{site.data.alerts.callout_success}} your callout_success content {{site.data.alerts.end}}
callout_warning | {{site.data.alerts.callout_warning}} your callout_warning content {{site.data.alerts.end}}
callout_info | {{site.data.alerts.callout_info}} your callout_info content {{site.data.alerts.end}}
{%endraw%}
Here's the syntax for a callout:
The following demonstrate the formatting for each 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 %}
```
{{site.data.alerts.callout_danger}}<b>callout_danger</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
{{site.data.alerts.end}}
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" %}
{{site.data.alerts.callout_default}}
<b>callout_default</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
{{site.data.alerts.end}}
To include paragraph breaks, use `<br/><br/>` inside the callout:
{{site.data.alerts.callout_primary}}
<b>calloutprimary</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
{{site.data.alerts.end}}
```
{% 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. <br/><br/>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 %}
```
{{site.data.alerts.callout_success}}
<b>calloutsuccess</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
{{site.data.alerts.end}}
Here's the result:
{{site.data.alerts.callout_info}}
<b>calloutinfo</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
{{site.data.alerts.end}}
{% 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. <br/><br/>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" %}
{{site.data.alerts.callout_warning}}
<b>calloutwarning</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
{{site.data.alerts.end}}
The type options are as follows:
* `danger`
* `default`
* `primary`
* `success`
* `info`
* `warning`
## Blast a warning to users
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.
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.
Here's an example of each different type of callout:
## Using Markdown inside of notes
{% 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" %}
You can't use Markdown formatting inside alerts. This is because the alerts leverage HTML, and you can't use Markdown inside of HTML tags. It's very easy to forget this, which is why I recommend using HTML formatting for links in every case. This way you're less likely to forget to switch into HTML mode when you're writing content in a tip. You must remember, however, to avoid Markdown with code and bold formatting inside of notes.
{% 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.
## Validity checking
If you have some of the syntax wrong with an alert or callout, you'll see an error when Jekyll tries to build your site. The error may look like this:
```
{% 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.
## 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.

74
mydoc/mydoc_hyperlinks.md
View File

@ -28,25 +28,15 @@ If you need to use HTML, use the normal syntax:
When linking to internal pages, you can use this same syntax:
```
[Sample]({{ "/page" | prepend: site.baseurl }})
[Sample]({{ "/permalink" | prepend: site.baseurl }})
```
OR
```html
<a href="{{ "/page" | prepend: site.baseurl }}">page</a>
<a href="{{ "/permalink" | prepend: site.baseurl }}">page</a>
```
I find that using the HTML formatting is easiest. Store the code in a shortcut in aText to populate it easily.
## Avoiding broken links
In general, avoid broken links and outdated titles in links by doing the following:
* Where possible, avoid using the exact titles in link names. For example, if you write, see the <a href="{{ "/mydoc_hyperlinks/" | prepend: site.baseurl}}">Links</a> page, this title is likely to become more outdated than if you were to write, learn how to <a href="{{ "/mydoc_hyperlinks/" | prepend: site.baseurl}}">manage links</a>.
* Use a broken link checker on your site output to see if links are broken.
* Generate a PDF, since the PDF tends to highlight broken links more forcefully.
## Managed Links
You can also adopt an indirect-reference systems for managing links. This "managed links" approach involves storing the link text in YAML syntax.
@ -75,10 +65,10 @@ sidebar:
---
```
From the site output folder (in \_site), open urls.txt and observe that it is properly populated (blank spaces between entries doesn't matter). Then manually copy the contents from the urls.txt and insert it into the \_data/urls.yml file in your project folder. Alternatively, run the urls-update.sh file:
From the site output folder (in \_site), open urls.txt and observe that it is properly populated (blank spaces between entries doesn't matter). Then either manually copy the contents from the urls.txt and insert it into the \_data/urls.yml file in your project folder. Or just run the urls-update.sh file:
```
. urls-update.txt
. urls-update.sh
```
This will move and rename the file through a script.
@ -109,7 +99,7 @@ After downloading the theme, you can [get started in building the theme]({{site.
```
{% endraw %}
Note that `.url` is used instead of `.link`.
Note that `.url` is used instead of `.link` when using customized text links like this.
If you're in HTML and can't use Markdown, then use the following code:
@ -125,11 +115,51 @@ You shouldn't have to transfer the contents from the urls.txt file into your YAM
I also added a simple script called "run.sh" that performs the urls-update.sh command prior to running Jekyll serve, so you can kill two birds with one stone.
Note that for the index.html file, which doesn't have a permalink, this file is not included in the urls.txt generation. To link to the homepage, just refer users to the root url of your site.
Note that for the index.html file, which doesn't have a permalink, this file is not included in the urls.txt generation. The frontmatter in the index.md file (`type: homepage`) triggers an exclusion from urls.txt because the empty name makes the yaml file invalid. To link to the homepage, just refer users to the root url of your site {% raw %}(`{{site.url}}` or `{{site.url}}{{site.baseurl}}`{% endraw %}).
Overall, by using managed links, you're less likely to end up with broken links.
{{site.data.alerts.tip}} To avoid having to remember this long syntax, use a text macro program like <a href="https://itunes.apple.com/us/app/atext/id488566438?mt=12">aText</a>. {{site.data.alerts.end}}
## Bookmark links to sections on other pages
Suppose you want to link to a specific section on another page. First make sure you name the section title with something table. Although Kramdown automatically adds ID tags to heading elements, if you change the heading title, the ID will likewise change. Therefore it's best to manually specify the section titles you plan to link to.
Here's how you specify an ID for a heading in Kramdown:
```
## My heading {#myheading}
```
Link to it using this syntax:
```
[{{site.data.urls.your-page-permalink.title}}]({{site.data.urls.your-page-permalink.url | append: "#myheading"}})
```
Or using HTML:
```
<a href="{{site.data.urls.your-page-permalink.url | append: "#myheading"}}">{{site.data.urls.your-page-permalink.title}}</a>
```
Granted, this is somewhat long, but it's the only way to continue to leverage the automated links from urls.yaml. You want to avoid manually referencing links since they are much more prone to break when you specify them that way.
However, I'm not too worried about this lengthy syntax because I think linking to sections on pages is somewhat fragile anyway. When you're editing sections, you generally don't know what URLs you have pointing to that section. The custom ID tag on that section is the best reminder that you are linking to the section.
## Bookmark links to sections on the same page
If you're just linking to a section on the same page, the syntax is simple:
```
[My heading](#myheading)
```
## How to tell what links point to a page
There's no automated way to tell what links you have pointing to a page. This is one of the shortcomings of static site generators. The only way is to search your project for the page title. This is simple in Webstorm (Cmd + Shift + F), and it's one of the reasons I like Webstorm.
If you change a page title, you generally want to search in your project and update all references to the page to the new page name. You can do this easily through the Global Replace command (Cmd + Shift + R).
## Always make sure your TOC page is accurate
@ -141,7 +171,7 @@ This is the only sane way to locate your pages when you have hundreds of pages i
## Checking for broken links
Another way to ensure you don't have any broken links in your output is to [generate a PDF]({{site.data.urls.mydoc_generating_pdfs.url}}). When you generate a PDF, look for the following two problems in the output:
One way to ensure you don't have any broken links in your output is to [generate a PDF]({{site.data.urls.mydoc_generating_pdfs.url}}). When you generate a PDF, look for the following two problems in the output:
* page 0
* see .
@ -151,3 +181,11 @@ Both instances indicate a broken link. The "page 0" indicates that Prince XML co
If you see "see ." it means that the reference (for example, {% raw %}`{{mylink...}}`{% endraw %} doesn't actually refer to anything. As a result, it's simply blank in the output.
{{site.data.alerts.note}} To keep Prince XML from trying to insert a cross reference into a link, add <code>class="noCrossRef"</code> to the link. {{site.data.alerts.end}}
## Avoiding broken links
In general, avoid broken links and outdated titles in links by doing the following:
* Where possible, avoid using the exact titles in link names. For example, if you write, see the <a href="{{ "/mydoc_hyperlinks/" | prepend: site.baseurl}}">Links</a> page, this title is likely to become more outdated than if you were to write, learn how to <a href="{{ "/mydoc_hyperlinks/" | prepend: site.baseurl}}">manage links</a>.
* Use a broken link checker on your site output to see if links are broken.
* Generate a PDF, since the PDF tends to highlight broken links more forcefully.

4
mydoc/mydoc_tables.md
View File

@ -43,7 +43,7 @@ cell 2a | cell 2b
## jQuery datables
You also have the option of using a [jQuery datatable](https://www.datatables.net/), which gives you some more options. If you want to use a jQuery datatable, then add `datatable: active` in a page's frontmatter. This will load the right jQuery datatable scripts for the table on that page only (rather than loading the scripts on every page of the site.)
You also have the option of using a [jQuery datatable](https://www.datatables.net/), which gives you some more options. If you want to use a jQuery datatable, then add `datatable: true` in a page's frontmatter. This will load the right jQuery datatable scripts for the table on that page only (rather than loading the scripts on every page of the site.)
Also, you need to add this script to trigger the jQuery table on your page:
@ -161,4 +161,4 @@ Notice a few features:
Read more of the [datatable documentation](https://www.datatables.net/manual/options) to get a sense of the options you can configure. You should probably only use datatables when you have long, massive tables full of information.
{{site.data.alerts.note}} Try to keep the columns to 3 or 4 columns only. If you add 5+ columns, your table may create horizontal scrolling with the theme.{{site.data.alerts.end}}
{{site.data.alerts.note}} Try to keep the columns to 3 or 4 columns only. If you add 5+ columns, your table may create horizontal scrolling with the theme. Additionally, keep the column heading titles short.{{site.data.alerts.end}}

3
urls-update.sh
View File

@ -1,2 +1,3 @@
cd _site
mv urls.txt ../_data/urls.yml
mv urls.txt ../_data/urls.yml
cd ../

57
urls.txt
View File

@ -7,37 +7,62 @@ sidebar:
- product2_sidebar
---
{% comment %}
_
_ __ ___ _ _ __| | ___ ___
| '_ ` _ \| | | |/ _` |/ _ \ / __|
| | | | | | |_| | (_| | (_) | (__
|_| |_| |_|\__, |\__,_|\___/ \___|
|___/
{% endcomment %}
{% for sidebar in page.sidebar %}
{% for entry in site.data.sidebars[sidebar].entries %}
{% for folder in entry.folders %}
{% for folderitem in folder.folderitems %} {% unless folderitem.type == "frontmatter" or folderitem.external_url or folderitem.type == "homepage" %}
{% for folderitem in folder.folderitems %} {% unless folderitem.type == "frontmatter" or folderitem.external_url %}
{{folderitem.url | replace: "/", "" }}:
title: "{{folderitem.title }}"
url: "{{folderitem.url | prepend: site.baseurl }} '{{folderitem.title}}'"
link: "<a href='{{folderitem.url | prepend: site.baseurl }}' title='{{folderitem.title}}'>{{folderitem.title}}</a>"
url: {{folderitem.url | prepend: site.baseurl }}
link: <a href="{{folderitem.url | prepend: site.baseurl }}">{{folderitem.title}}</a>
{% endunless %}
{% for subfolders in folderitem.subfolders %}
{% for subfolderitem in subfolders.subfolderitems%} {% unless subfolderitem.type == "frontmatter" or subfolderitem.external_url or subfolderitem.type == "homepage" %}
{% for subfolderitem in subfolders.subfolderitems%} {% unless subfolderitem.type == "frontmatter" or subfolderitem.external_url %}
{{subfolderitem.url | replace: "/" }}:
title: "{{subfolderitem.title}}"
url: "{{subfolderitem.url| prepend: site.baseurl }} '{{subfolderitem.title}}'"
link: "<a href='{{subfolderitem.url | prepend: site.baseurl }}' title='{{subfolderitem.title}}'>{{subfolderitem.title}}</a>"
url: {{subfolderitem.url| prepend: site.baseurl }}
link: <a href="{{subfolderitem.url | prepend: site.baseurl }}">{{subfolderitem.title}}</a>
{% endunless %}
{% endfor %}
{% endfor %}
{% endfor %}
{% endfor %}
{% endfor %}
{% endfor %}
{% comment %}
_
| |_ ___ _ __ _ __ __ ___ __
| __/ _ \| '_ \| '_ \ / _` \ \ / /
| || (_) | |_) | | | | (_| |\ V /
\__\___/| .__/|_| |_|\__,_| \_/
|_|
{% endcomment %}
{% for entry in site.data.topnav.topnav %}
{% for item in entry.items %}
{% unless item.external_url %}
{{item.url | replace: "/", ""| replace: "\", ""}}:
title: "{{item.title}}"
url: "{{item.url | replace: "/", ""| replace: "\", ""}}"
link: "<a href='{{item.url}}'>{{item.title}}</a>"
{% endunless %}
{% endfor %}
{% endfor %}
{% for entry in site.data.topnav.topnav_dropdowns %}
{% for folder in entry.folders %}
{% for folderitem in folder.folderitems %}
{% unless folderitem.external_url %}
{{folderitem.url | replace: "/", ""| replace: "\", "" }}:
title: "{{folderitem.title}}"
url: "{{folderitem.url| replace: "/", ""| replace: "\", ""}}"
link: "<a href='{{folderitem.url}}'>{{folderitem.title}}</a>"
{% endunless %}
{% endfor %}
{% endfor %}
{% endfor %}