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

removing gh-pages branch and putting everything in master

Browse Source
This commit is contained in:
Tom Johnson
2015-04-20 12:10:04 -07:00
parent 8c1ccbcc57
commit f0b925337f
360 changed files with 119491 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
pages/formatting/alerts.md Normal file
View File

@ -0,0 +1,88 @@
---
title: Alerts
permalink: /alerts/
audience: writer, designer
tags: formatting
---
{% include linkrefs.html %}
Alerts are little warnings, info, or other messages that you have called out in special formatting. In order to use these alerts or callouts, put this include at the top of your page, just below your frontmatter:
{%raw%}
```liquid
{% include linkrefs.html %}
```
{%endraw%}
Then insert any an alert or callout as described in the following sections.
## Alerts
You can insert an alert by using any of the following code.
{%raw%}
alert | code
------|---------
note | {{note}} your note {{end}}
tip | {{tip}} your tip {{end}}
warning | {{warning}} your warning {{end}}
important | {{important}} your important info {{end}}
{%endraw%}
The following demonstrate the formatting associated with each alert.
{{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. {{end}}
{{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. {{end}}
{{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. {{end}}
{{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. {{end}}
## 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.
{%raw%}
callout | code
------|---------
callout_default | {{callout_default}} your callout_default content {{end}}
callout_primary | {{callout_primary}} your callout_primary content {{end}}
callout_success | {{callout_success}} your callout_success content {{end}}
callout_primary | {{callout_primary}} your callout_primary content {{end}}
callout_warning | {{callout_warning}} your callout_warning content {{end}}
callout_info | {{callout_info}} your callout_info content {{end}}
{%endraw%}
The following demonstrate the formatting for each callout.
{{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.
{{end}}
{{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.
{{end}}
{{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.
{{end}}
{{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.
{{end}}
{{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.
{{end}}
{{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.
{{end}}
## Blast a warning to users
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.

170
pages/formatting/icons.md Normal file
View File

@ -0,0 +1,170 @@
---
title: Icons
permalink: /icons/
audience: writer, designer
tags: formatting
---
The theme has two font icon sets integrated: Font Awesome and Glyphicons Halflings. The latter is part of Bootstrap, while the former is independent.
## See Font Awesome icons available
Go to the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/)
The Font Awesome icons allow you to adjust their size by simply adding `fa-2x`, `fa-3x` and so forth as a class to the icon to adjust their size to two times or three times the original size. As vector icons, they scale crisply at any size.
Here's an example of how to scale up a camera icon:
```html
<i class="fa fa-camera-retro"></i> normal size (1x)
<i class="fa fa-camera-retro fa-lg"></i> fa-lg
<i class="fa fa-camera-retro fa-2x"></i> fa-2x
<i class="fa fa-camera-retro fa-3x"></i> fa-3x
<i class="fa fa-camera-retro fa-4x"></i> fa-4x
<i class="fa fa-camera-retro fa-5x"></i> fa-5x
```
Here's what they render to:
<i class="fa fa-camera-retro"></i> 1x
<i class="fa fa-camera-retro fa-lg"></i> fa-lg
<i class="fa fa-camera-retro fa-2x"></i> fa-2x
<i class="fa fa-camera-retro fa-3x"></i> fa-3x
<i class="fa fa-camera-retro fa-4x"></i> fa-4x
<i class="fa fa-camera-retro fa-5x"></i> fa-5x
With Font Awesome, you always use the `i` tag with the appropriate class. You also implement `fa` as a base class first. You can use font awesome icons inside other elements. Here I'm using a Font Awesome class inside a Bootstrap alert:
```html
<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>This is a special warning message.
```
Here's the result:
<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle fa-lg"></i> This is a special warning message.</div>
Some of the Bootstrap styles are pre-coded with Font Awesome and stored in the linkrefs.html file in `capture` tags. That file includes the following:
{% raw %}
```html
{% capture tip %}<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip: </b>{% endcapture %}
{% capture note %}<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note: </b>{% endcapture %}
{% capture important %}<div class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> <b>Important: </b>{% endcapture %}
{% capture warning %}<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>{% endcapture %}
{% capture end %}</div>{% endcapture %}
```
{% endraw %}
This means you can insert a tip, note, warning, or important alert simply by using these tags:
{% raw %}
```
{{note}} Add your note here. {{end}}
```
{% endraw %}
Here's the result:
{{note}} Add your note here. {{end}}
You can innovate with your own combinations. Here's a similar approach with a check square:
```html
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o fa-lg"></i> This is a special success message.</div>
```
And the result:
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o fa-lg"></i> This is a special success message.</div>
Grab the right class name from the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/) and then implement it by following the pattern shown previously.
## Glyphicon icons available
Glyphicons work similarly to Font Awesome. Go to the [Glyphicons library](http://getbootstrap.com/components/#glyphicons) to see the icons available.
Although the Glyphicon Halflings library doesn't provide the scalable classes like Font Awesome, there's a [StackOverflow trick](http://stackoverflow.com/questions/24960201/how-do-i-make-glyphicons-bigger-change-size) to make the icons behave in a similar way. This theme's stylesheet (customstyles.css) includes the following to the stylesheet:
```css
.gi-2x{font-size: 2em;}
.gi-3x{font-size: 3em;}
.gi-4x{font-size: 4em;}
.gi-5x{font-size: 5em;}
```
Now you just add `gi-5x` or whatever to change the size of the font icon:
```html
<span class="glyphicon glyphicon-globe gi-5x"></span>
```
And here's the result:
<span class="glyphicon glyphicon-globe gi-5x"></span>
Glypicons use the `span` element instead of `i` to attach their classes.
Here's another example:
```html
<span class="glyphicon glyphicon-download"></span>
```
<span class="glyphicon glyphicon-download"></span>
And magnified:
```html
<span class="glyphicon glyphicon-download gi-3x"></span>
```
<span class="glyphicon glyphicon-download gi-3x"></span>
You can also put glyphicons inside other elements:
```html
<div class="alert alert-danger" role="alert">
<span class="glyphicon glyphicon-exclamation-sign" aria-hidden="true"></span>
<b>Error:</b> Enter a valid email address
</div>
```
<div class="alert alert-danger" role="alert">
<span class="glyphicon glyphicon-exclamation-sign" aria-hidden="true"></span>
<b>Error:</b> Enter a valid email address
</div>
## Callouts
The previously shown alerts might be fine for short messages, but with longer notes, the solid color takes up a bit of space. In this theme, you also have the option of using callouts, which are pretty common in Bootstrap's documentation but surprisingly not offered as an explicit element. Their styles have been copied into this theme, in a way similar to the alerts:
```html
<div class="bs-callout bs-callout-info">
This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. </div>
```
<div class="alert alert-info" role="alert"><span class="glyphicon glyphicon-question-sign"></span> This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. </div>
And here's the shortcode:
{% raw %}
```
{{callout_info}}<div class="bs-callout bs-callout-info">{{end}}
{% endraw %}
```
You can use any of the following:
{% raw %}
```
{{callout_danger}}
{{callout_default}}
{{callout_primary}}
{{callout_success}}
{{callout_info}}
{{callout_warning}}
```
{% endraw %}

36
pages/formatting/images.md Normal file
View File

@ -0,0 +1,36 @@
---
title: Images
permalink: /images/
audience: writer, designer
tags: formatting
---
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. The difference here is that the asset doesn't have a permalink, so here the file path actually matters.
## Images
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:
{% raw %}
```html
<img src="{{ "/images/jekyll.png" | prepend: site.baseurl }}">
```
{% endraw %}
Here's a sample:
<img title="my sample image" src="{{ "/images/jekyll.png" | prepend: site.baseurl }}">
## SVG Images
You can also embed SVG graphics. Here's a sample embed:
```html
<img src="{{site.baseurl}}/images/helpapi.svg" style="width: 650px;"/>
```
Here's the result:
<img src="{{site.baseurl}}/images/helpapi.svg" style="width: 650px;"/>
SVG images will expand to the size of their artboard, so you can either set the artboard the right size when you create the graphic in Illustrator, or you can set an inline style that confines the size to a certain width as shown in the code above.

26
pages/formatting/labels.md Normal file
View File

@ -0,0 +1,26 @@
---
title: Labels
permalink: /labels/
audience: writer, designer
tags: formatting
---
These labels might come in handy for labeling things, such as POST, DELETE, UPDATE methods for endpoints. You can use any classes from Bootstrap in your content.
```html
<span class="label label-default">Default</span>
<span class="label label-primary">Primary</span>
<span class="label label-success">Success</span>
<span class="label label-info">Info</span>
<span class="label label-warning">Warning</span>
<span class="label label-danger">Danger</span>
```
<span class="label label-default">Default</span>
<span class="label label-primary">Primary</span>
<span class="label label-success">Success</span>
<span class="label label-info">Info</span>
<span class="label label-warning">Warning</span>
<span class="label label-danger">Danger</span>
You can have a label appear within a heading simply by including the span tag in the heading. However, you can't mix Markdown syntax with HTML, so you'd have to hard-code the heading ID for the auto-TOC to work.

64
pages/formatting/links.md Normal file
View File

@ -0,0 +1,64 @@
---
title: Links
permalink: /links/
audience: writer, designer
tags: [formatting, navigation]
---
## Create a link
There are several ways to create links: Markdown, HTML, or keyref-style. I'll recommend the simplest way to create links:
## Markdown links
Markdown link pointing to an external site:
```
[Google](http://google.com)
```
## HTML links
HTML link pointing to an internal site:
{% raw %}
```
<a href="{{ "/syntax_highlighting" | prepend: site.baseurl }}">Syntax Highlighting</a>
```
{% endraw %}
## Re-using links
For internal links, it's a best practice to store the link in an internal file so that you can easily update all references to the link.
In this theme, the includes folder contains a linkrefs.html file where the capture tags are stored:
{%raw%}
```html
{% capture supported_features %}<a href="{{"/supported_features" | prepend: site.baseurl}}">Supported Features</a>{% endcapture %}
```
{%endraw%}
Anything between the capture tags is inserted when you use capture variable.
To insert a link to the above, you would just add this in your content. First put the linksrefs.html include below your frontmatter:
{%raw%}
```html
{% include linkrefs.html %}
```
{%endraw%}
Then insert the variable from your captured link:
{%raw%}
```
For more information, see {{supported_features}}.
```
{%endraw%}
If you ever change the link, all references pointing to {{supported_features}} will automatically be updated. It's also easy to do a find and replace operation looking for "{{supported_features}}".
## Folder paths irrelevant
Even though you may group pages into subfolders, when you reference a page, you reference it by the permalink regardless of the subfolder it happens to be in. So even if you have formatting/syntax_highlighting, you link to it with `syntax_highlighting` instead of `formatting/syntax_highlighting` because that's the topic's permalink. Jekyll iterates through all pages in the page namespace to locate one that contains the matching permalink.

80
pages/formatting/pages.md Normal file
View File

@ -0,0 +1,80 @@
---
title: Pages
permalink: /pages/
audience: writer, designer
tags: [getting-started, formatting]
---
Use a text editor such as Sublime Text, WebStorm, or Emacs to create pages. Make sure each page has frontmatter at the top like this:
```
---
title: Getting started
permalink: /getting_started/
tags: newbies
---
```
Frontmatter is always formatted with three hyphens at the top and bottom. Your frontmatter must have a `title` and `permalink` value. The `tags` property is optional but potentially useful for knowledge-base articles. Make all tags single words, with hyphens if needed. Separate them with commas.
Pages can be either Markdown or HTML format. If you use Markdown, you can also include HTML formatting where needed. But not vice versa -- if you use HTML (as your file extension), you can't insert Markdown content.
Also, if you use HTML inside a Markdown file, you cannot use Markdown inside of HTML. But you can use HTML inside of Markdown.
For your Markdown files, note that a space or two indent will set text off as code or blocks, so avoid spacing indents unless intentional.
## Where to save pages
Store all your pages inside the pages folder. The number of subfolders inside your pages directory doesn't matter. You won't have to use paths (such as ../) when linking to pages. Instead, all the pages will be pulled out to the root directory, and links are established through the permalink value in the page's frontmatter.
If you want to use a colon in your page title, you must enclose the title's value in quotation marks.
## Pages versus posts
Most of the theme is designed for using pages, but you can also use posts. Posts are intended for blog entries. They have dates in the filenames, and they sort chronologically when get the posts. Create posts inside the _posts folder.
The latest_posts.html file shows the latest posts. The tagindex.html file sorts posts by tags. The archive.html sorts posts by date.
{{note}} I haven't done much testing with posts, so you may run into some snags there. {{end}}
## Github-flavored Markdown
You can use standard Multimarkdown syntax for tables. You can also use fenced code blocks. The configuration file shows the Markdown processor and extensiosn:
```
markdown: redcarpet
redcarpet:
extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "tables", "with_toc_data"]
```
These extensions mean the following:
- don't italicize words with underscores
- allow three backticks before and after code blocks instead of `<pre>` tags
- automatically create links out of URLs
- allow table syntax
- add ID tags to headings automatically
## Related posts
By default, posts contain related posts beneath them. To disable this, add `related_pages: none` or `related_posts: none` in the frontmatter of the page.
Pages have tags instead of related posts. (It turns out that creating "Related pages" in Jekyll is much more difficult than related posts.)
## Automatic mini-TOCs
By default, a mini-TOC appears at the top of your pages and posts. If you don't want this, you can remove the {% raw %}`{% include toc.html %}` {% endraw %} from the layouts/page.html and layouts/posts.html files.
If you don't want the TOC to appear for a specific page, add `toc: false` in the frontmatter of the page.
This frontmatter requires you to use the `##` syntax for headings. If you use `<h2>` elements, then you must add an ID attribute for the h2 element in order to get it to appear in the mini-TOC.
## Specify a particular page layout
The configuration file sets the default layout for pages as the page layout. You can create other layouts inside the layouts folder. You can then specify that the page use that particular layout by adding `layout: mylayout.html` in the page's frontmatter. Whatever layout you specify in the frontmatter of a page will override the layout default set in the configuration file.
## Comments
Disqus, a commenting system, is integrated into the theme. In the configuration file, specify the Disqus code for the universal code, and Disqus will appear. If you don't add a Disqus value, the Disqus code isn't included.

35
pages/formatting/syntax_highlighting.md Normal file
View File

@ -0,0 +1,35 @@
---
title: Syntax highlighting
permalink: /syntax_highlighting/
audience: writer, designer
tags: formatting
---
For syntax highlighting, use fenced code blocks optionally followed by the language syntax you want:
```ruby
def foo
puts 'foo'
end
```
Fenced code blocks require a blank line before and after.
If you're using an HTML file, you can also use the `highlight` command with Liquid markup:
{% raw %}
```ruby
{% highlight ruby %}
def foo
puts 'foo'
end
{% endhighlight %}
```
{% endraw %}
The theme has syntax highlighting configured in the configuration file as follows:
```
highlighter: rouge
```

117
pages/formatting/tables.md Normal file
View File

@ -0,0 +1,117 @@
---
title: Tables
permalink: /tables/
---
## Multimarkdown Tables
You can use Multimarkdown syntax for tables. The following shows a sample:
```
Column 1 | Column 2
--------|----------
cell 1a | cell 1b
cell 2a | cell 2b
```
This renders to the following:
Column 1 | Column 2
--------|----------
cell 1a | cell 1b
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: true` in a page's frontmatter. This will enable the right scripts for the table on that page only (rather than loading the scripts on every page of the site.)
Also, add the scripts to trigger the jQuery table on your page:
```js
<script>
$(document).ready(function(){
$('table.display').DataTable( {
paging: true,
stateSave: true,
searching: true
}
);
});
</script>
```
The available options for the datable are described in the [datatable documentation](https://www.datatables.net/manual/options), which is excellent.
Additionally, you must add a class of `display` to the table. (You can change the class, but then you'll need to change the trigger above from `table.display` to whatever class you want to you. You might have different triggers with different options for different tables.)
Since Markdown doesn't allow you to add classes to tables, you'll need to use HTML for any datatables. Here's an example:
```html
<table id="sampleTable" class="display">
<thead>
<tr>
<th>Parameter</th>
<th>Description</th>
<th>Type</th>
<th>Default Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>Parameter 1</td>
<td>Sample description
</td>
<td>Sample type</td>
<td>Sample default value</td>
</tr>
<tr>
<td>Parameter 2</td>
<td>Sample description
</td>
<td>Sample type</td>
<td>Sample default value</td>
</tr>
</tbody>
</table>
```
This renders to the following:
<script>
$(document).ready(function(){
$('table.display').DataTable( {
paging: false,
stateSave: true
}
);
});
</script>
<table id="sampleTable" class="display">
<thead>
<tr>
<th>Parameter</th>
<th>Description</th>
<th>Type</th>
<th>Default Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>Parameter 1</td>
<td>Sample description
</td>
<td>Sample type</td>
<td>Sample default value</td>
</tr>
<tr>
<td>Parameter 2</td>
<td>Sample description
</td>
<td>Sample type</td>
<td>Sample default value</td>
</tr>
</tbody>
</table>

25
pages/formatting/videos.md Normal file
View File

@ -0,0 +1,25 @@
---
title: Videos
permalink: /videos/
audience: writer, designer
tags: formatting
---
The theme has the [video.js](http://www.videojs.com/) player integrated. But the scripts only appear on a page or post if you have certain frontmatter in that page or post. If you want to embed a video in a page and use the Video JS player, add `video: true` in your frontmatter of a page or post, and then add code like this where you want the video to appear:
{% raw %}
```html
<video id="scenario-1" class="video-js vjs-default-skin" controls
preload="auto" width="640" height="360" data-setup='{}'>
<source src="{{site.baseurl}}/videos/scenario1.mp4" type='video/mp4'>
</video>
```
{% endraw %}
You'll know it's working if the video wrapper looks like the one here: [video.js: the open source HTML5 video player](http://www.videojs.com/). The play button will be in the upper-left corner. If you want the player button in the middle, change the class to `video-js vjs-default-skin vjs-big-play-centered`.
Here are [more details on this video player](https://github.com/videojs/video.js/blob/stable/docs/guides/setup.md).
There are a number of javascript files included in inside the video-js folder inside the js folder. This allows the player to work offline.
Note that if some of the js doesn't load correctly, the default fallback player is the regular HTML5 video player available via the browser. However, I don't think the built-in video players work very well (you can't easily scrub around the video without seeing lots of buffering and other issues.)