Permalink
Browse files

doc: Readme

  • Loading branch information...
MikeMitterer committed Mar 30, 2015
1 parent b7314fc commit 8e33ffc48474e866f0dfbd439cef1bc0197e64f7
View
34 LICENSE
@@ -0,0 +1,34 @@
Copyright (c) 2015, Michael Mitterer (office@mikemitterer.at),
IT-Consulting and Development Limited, Austrian Branch
All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the Michael Mitterer, IT-Consulting
and Development Limited, Austrian Branch, nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL Michael Mitterer,
IT-Consulting and Development Limited, Austrian Branch, BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
View
233 README.md
@@ -1,21 +1,222 @@
## Review
## SiteGen
- WebCast auf [YT][1]
- [Mustache][3]
- [Markdown Cheatsheet][4]
A simple static site generator in [Dart][dart], webserver included.
You can write your pages in HTML or [Markdown][markdown]. For Templates [Mustache][mustache] is supported.
LivePage!!!!
https://chrome.google.com/webstore/detail/livepage/pilnojpmdoofaelbinaeodfpjheijkbh
A webserver for a quick review is included. On Mac you also get automatic page refresh. On other
platforms you could try [LivePage][livepage] chrome extension for maximum productivity.
### Basis auf pub
- [StillShot][2]
- [Plugins][5]
[Here][example] you can see a typical site structure.
### Sonstiges
Extension für Mustach-Files: .mustache
```
├── .sitegen
│   ├── refreshChromium-1.0.applescript
│   └── site.yaml
├── html
│   ├── _content
│   │   ├── about
│   │   │   └── index.html
│   │   ├── index.html
│   │   ├── markdown.md
│   │   ├── piratenames.json
│   │   └── xtreme.html
│   └── _templates
│   ├── default.html
│   └── info_page.html
└── web
├── about
│   ├── index.html
│   └── packages -> ../../packages
├── index.html
├── main.dart
├── markdown.html
├── packages -> ../packages
├── piratenames.json
├── styles
│   ├── main.css
│   ├── main.scss
│   └── packages -> ../../packages
└── xtreme.html
```
[1]: http://www.youtube.com/watch?v=hvQCXDWh7Wg&feature=share&list=PLYVl5EnzwqsQs0tBLO6ug6WbqAbrpVbNf
[2]: https://pub.dartlang.org/packages/stillshot
[3]: https://github.com/janl/mustache.js/
[4]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
[5]: https://pub.dartlang.org/packages/plugins
.sitegen: This is where your site.yaml lives
This folder is also used to store autgenerated scripts - in the case above you can see
the script to refresh Chromium on Mac
html/_content: This is where **SiteGen** will look for your files to generate the site from.
The following file-formats are supported:
- .md
- .markdown
- .dart
- .js
- .json
- .html
- .scss
- .css
html/_templates: The directory containing your HTML+Mustache templates.
web: Following Dart conventions - this is your default output directory.
## site.yaml
**Optional** [YAML][yaml] file that stores your global values and config options.
Values set here can be accessed from all templates and markdown files.
```
site_options:
author: Mike Mitterer
```
Can be used in you template (default.html) as
```
<span>{{_site.author}}</span>
```
You can also use site.yaml to overwrite your **SiteGen** default configuration.
Supported vars:
- content_dir: html/_content
- template_dir: html/_templates
- output_dir: web
- workspace: .
- date_format: dd.MM.yyyy
- yaml_delimeter: ~~~
- use_markdown: true
- default_template: default.html
- sasscompiler: sassc
## Markdown
**SiteGen** lets you use [markdown][markdown] to write your site content. At the beginning of each markdown file, you
have the option to use a [YAML][yaml] block to define custom values that you can inject into your templates. Example:
title: A Blog Post
published: 01/01/2014
category: example
tags:
- StillShot
- Rants
- Etc.
~~~~~~
{{title}}
Normal Markdown content here...
As you can see, a line of tildes (`~`) is used to designate your YAML block. You can access/inject your values into
your pages using [mustache template syntax][mustache]. You can do this either inside your dedicated HTML/mustache templates:
<ul>
{{#tags}}
<li>{{.}}</li>
{{/tags}}
</ul>
Or, you can embed your values within the markdown file itself:
{{#tags}}
- __{{.}}__
{{/tags}}
so you can take advantage of templating and markdown at the same time.
Simply place all your files in your `content_dir` and **SiteGen** will generate your site accordingly.
If your markdown file has a .md extension it will be renamed to .html.
## Templates
As mentioned above, you can access any variables set within your markdown files from your templates using mustache. Options
set from your `site.yaml / site_options` can be accessed through the `_site` variable, like so:
<h1>{{ _site.author}}</h1>
where `author` is a property defined in your `site.yaml / site_options`. You can access these values from your markdown or html files as well.
Every page and template has access to the following values:
- `title`: post title, usually set inside each markdown file, but is set to name of markdown file if left blank
- `_site`: site.yaml values
- `_date`: the post/markdown file's _last modified_ date
- `_content`: converted markdown content (only accessible from templates)
- `_page.relative_to_root`: is replaced with some '../' depending on the nesting level of your page (check about/index.html)
The default template is 'default.html' but you can overwrite this behavior if you add a 'template' var to the yaml-block of your content file
template: info_page
## SASS
If SiteGen finds a .scss file in your output dir (web) it compiles it to the corresponding .css file.
# Install
Install
```shell
pub global activate sitegen
```
Update
```shell
# activate git-help again
pub global activate sitegen
```
Uninstall
```shell
pub global deactivate sitegen
## Usage
```shell
Usage: sitegen [options]
-s, --settings Prints settings
-h, --help Shows this message
-g, --generate Generate site
-w, --watch Observes SRC-dir
--serve Serves your site
--port Sets the port to listen on
(defaults to "8000")
-v, --loglevel Sets the appropriate loglevel
[info, debug, warning]
Sample:
'Observes the default dirs and serves the web-folder: 'sitegen -w --serve'
'Generates the static site in your 'web-folder': 'sitegen -g'
```
Go to your project root (this is where your pubspec.yaml is) and type:
sitegen -w --serve
If you are using Chromium on Mac you will get a automatic page refresh for free!
Now play with sitegen and watch my screencast...
### Thanks
I want to thank "Enrique Gavidia" for his [stillshot][stillshot] package that I used as basis for **SiteGen**
### License
Copyright 2015 Michael Mitterer (office@mikemitterer.at),
IT-Consulting and Development Limited, Austrian Branch
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the License for the specific language
governing permissions and limitations under the License.
If this plugin is helpful for you - please [(Circle)](http://gplus.mikemitterer.at/) me
or **star** this repo here on GitHub
[dart]: https://www.dartlang.org/
[tracker]: https://github.com/MikeMitterer/dart-sitegen/issues
[markdown]: http://daringfireball.net/projects/markdown/syntax
[mustache]: http://mustache.github.io/mustache.5.html
[livepage]: https://chrome.google.com/webstore/detail/livepage/pilnojpmdoofaelbinaeodfpjheijkbh
[example]: https://github.com/MikeMitterer/dart-sitegen/tree/master/examples/simple
[yaml]: http://rhnh.net/2011/01/31/yaml-tutorial
[stillshot]: https://pub.dartlang.org/packages/stillshot
@@ -1,2 +1,11 @@
title: About
~~~
<span>INDEX!!!!..eeee</span>
<h2>Headline II</h2>
<div class="badge">
<div class="greeting">
Arrr! Me name is
</div>
<div class="name">
<span id="badgeName"> </span>
</div>
</div>
@@ -0,0 +1,18 @@
title: Pirate badge1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<div class="widgets">
<div>
<input type="text" id="inputName" maxlength="15" disabled>
</div>
<div>
<button id="generateButton" disabled>Aye! Gimme a name!</button>
</div>
</div>
<div class="badge">
<div class="greeting">
Arrr! Me name is
</div>
<div class="name">
<span id="badgeName"> </span>
</div>
</div>
@@ -1,3 +0,0 @@
main() {
}
@@ -3,7 +3,7 @@
# This is an example of a YAML comment which will be completely ignored.
# A basic variable definition
title: About StillShot
title: About SiteGen
# A list of strings. Surrounding your strings in quotes is optional,
# but some may require it so they don't interfere with YAML syntax.
@@ -29,7 +29,7 @@ links:
# You can even embed markdown in your YAML strings if you want (as long as you use the values
# in the markdown file itself -- markdown injected into html templates will not get evaluated).
tags:
- "[StillShot][stillshot]"
- "[SiteGen][sitegen]"
- "[Markdown][markdown]"
- "[Mustache][mustache]"
- "[YAML][yaml]"
@@ -41,43 +41,48 @@ date_format: yMd
# And here we manually define the template we want to use.
# Note the lack of a file extension. This is to have compatibility
# with any template file-type, though mustache embedded in plain
# old HTML is the default. If no template is defined here, StillShot
# old HTML is the default. If no template is defined here, SiteGen
# will use the one listed for 'default_template' in your site.yaml
template: info_page
# template: info_page
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#Wieder ein TEST
#{{title}} (Content)
###Subheadline
3 `~`'s is the minimum for designating and separating a [YAML][yaml] block, but they can be extended longer -- all that matters
is that the tildes (`~`) are on their own line.
And anything beyond that gets interpreted as [Markdown][markdown]!
[Markdown][markdown]!
You can even use template tags in here, for any variables you set in in the top YAML block, or in your `site.yaml` file:
This post's title is: "{{ title }}"
This file was last modified on {{ _date }}
Note that variables beginning with an underscore designate *implicit* metadata added by __StillShot__.
Note that variables beginning with an underscore designate *implicit* metadata added by __SiteGen__.
Some vars that are always available by default:
{{#default_vars}}
- {{.}}
{{.}}
{{/default_vars}}
And as you can see, you can also use mustache logic to iterate through yaml maps and lists:
Links are rendered incorrectly.
Bug: [https://github.com/dpeek/dart-markdown/issues/35](https://github.com/dpeek/dart-markdown/issues/35)
{{#links}}
- [{{name}}]({{url}})
- [{{name}}]({{url}})
{{/links}}
{{#tags}}
* {{.}}
* {{.}}
{{/tags}}
{{#authors}}
- {{.}}
- {{.}}
{{/authors}}
Note how you need to use a `.` to access a list item, but can access map/dict keys directly.
@@ -88,4 +93,4 @@ Same ideas apply when writing your actual HTML templates. See [mustache's docs][
[yaml]: http://rhnh.net/2011/01/31/yaml-tutorial
[markdown]: http://daringfireball.net/projects/markdown/syntax
[mustache]: http://mustache.github.io/mustache.5.html
[stillshot]: https://github.com/oblique63/StillShot
[sitegen]: https://github.com/MikeMitterer/dart-sitegen
Oops, something went wrong.

0 comments on commit 8e33ffc

Please sign in to comment.