Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thlorenz/dog
Developer blOGgin Engine, markdown based, made to be simple and fast, yet feature rich.
https://github.com/thlorenz/dog
Last synced: 2 months ago
JSON representation
Developer blOGgin Engine, markdown based, made to be simple and fast, yet feature rich.
- Host: GitHub
- URL: https://github.com/thlorenz/dog
- Owner: thlorenz
- Created: 2012-08-29T01:28:12.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2017-04-29T19:59:02.000Z (over 7 years ago)
- Last Synced: 2024-10-18T02:51:30.883Z (3 months ago)
- Language: JavaScript
- Homepage: http://thlorenz.com/blog/dog-tutorial
- Size: 1.19 MB
- Stars: 11
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
# dog [](http://travis-ci.org/thlorenz/dog)
## D *eveloper bl* OGging Engine
- markdown based
- code snippet support
- [embedded scriptie-talkie](http://thlorenz.github.io/scriptie-talkie-embed/) support
- syntax highlighting
- posts stored on file system
- provides html and default styles
- publishes via simple command line
- [Installing Dog](#installing-dog)
- [Dog Command Line](#dog-command-line)
- [scaffold](#scaffold)
- [preview](#preview)
- [publish](#publish)
- [unpublish](#unpublish)
- [summary](#summary)
- [help](#help)
- [includeStyles](#includestyles)
- [action aliases](#action-aliases)
- [Inlining code samples](#inlining-code-samples)
- [Syntax highlighted inlines](#syntax-highlighted-inlines)
- [Scriptie-Talkie inlines](#scriptie-talkie-inlines)
- [Dog Metatags](#dog-metatags)
- [Including Post Title](#including-post-title)
- [Including Post Creation Date](#including-post-creation-date)
- [Including Post Update Date](#including-post-update-date)
- [Including Post Tags](#including-post-tags)
- [Including external Code Snippets](#including-external-code-snippets)
- [Dog Provider](#dog-provider)
- [provideFrom](#providefrom)
- [concatentateStyles](#concatentatestyles)
- [provideAll](#provideall)
- [provideUpdatedSince](#provideupdatedsince)
- [copyImages](#copyimages)
- [getAllPosts](#getallposts)
- [getAllTags](#getalltags)
- [getPostMetadata](#getpostmetadata)
- [getPostHtml](#getposthtml)
- [blog directories](#blog-directories)
- [getStylesFiles](#getstylesfiles)
- [printSummary](#printsummary)
- [Styling](#styling)
- [Examples](#examples)
- [Blog Only](#blog-only)
- [Blog Site](#blog-site)
- [Tutorial](#tutorial)
## Installing Dog
In order to install dog globally to use its command line tool to manage your blog do:
`npm install -g dog`
In order to use dog's providing capabilities in order to serve your blog, install it locally to the project, i.e.,:
`npm install dog`
## Dog Command Line
dog allows you to manage your blog via simple a simple command line interface.
The commands follow a general pattern: `dog [options]`
The `` here is the directory that contains the 'post.md' on which the action is to be performed.
In only a few cases (i.e., when the action affects the entire blog) `` is omitted.
All of the actions assume that you created a blog directory and are currently in it unless you specify the `--root`
options (see below).
Lets run through the different actions one by one.
### scaffold
`dog scaffold`
Creates a blog skeleton including a sample post.
This is probably the first thing you want to do in order to start your blog.
### preview
`dog preview post`
Opens the rendered post in the browser.
### publish
`dog publish post [options]`
Publishes the post according to the given options.
Options:
- `--title`: The title to be applied to the post.
- `--tags`: The tags that will be added to the post
- `--root`: The root directory of your blog. Defaults to `./`, so you don't need it if you are executing this action
from the blog root.
This will add or update `post.json` inside the post directory as well as add it and its tags to `blog.json`.
dog will print out a record of the changes made.
If you publish an existing post again, only the updated date and any given options will be changed. Everything else will
stay as before.
**Example:** `dog publish getting-started --title "Getting started with dog" --tags "cli nodejs javascript"
### unpublish
`dog unpublish post`
This will remove the given post from the `blog.json` and delete the `post.json` from the post directory. Anything else
in the post's directory will be left untouched.
### summary
`dog summary`
Prints out a summary of your blog, including all metadata of each published post and important directories, e.g.,
`assets` and `images`.
### help
`dog help`
Prints out dog's help message.
### includeStyles
`dog includeStyles --styles "style1 style2 ..."`
Configures the blog provider to include the given styles from the `assets/styles` directory.
Most likely you will not need to change the default.
### action aliases
dog understands unambiguous short forms of action names in a similar way that nodejs's npm does.
Therefore `dog pub post` gets expanded to `dog publish post` while `dog s` is not sufficient since it could mean `dog
summary` or `dog scaffold`.
As a less useful option: `dog --action publish --post post --title "My Post"`
is equivalent to: `dog publish post --title "My Post"`.
## Inlining code samples
### Syntax highlighted inlines
Dog supports syntax highlighted inlined code samples the same way that [github flavored
markdown](https://help.github.com/articles/github-flavored-markdown) does.
**Example:**
Source (omit leading `-`)
```text
-```js
var a = 3;
-```
```
Result:
```js
var a = 3;
```
### Scriptie-Talkie inlines
If you prefer to show interactive [scriptie-talkie code samples](http://thlorenz.github.io/scriptie-talkie-embed/), please specify `'jsst'` (think **js**
**s**criptie **t**alkie) as the language, i.e. (again omit leading `-`)
```text
-```jsst
var a = 3;
-```
```
## Dog Metatags
Aside from the usual markdown directives dog supports a few more tags enclosed by `{{ }}` in order to include metadata
or external snippets.
Studying the 'getting-started' post included as a result of `dog scaffold` and comparing it to the rendered html - `dog
preview getting-started` should give you a good idea on how this works.
### Including Post Title
`{{ meta: title }}`
Will be replaced with the title found inside `post.json`.
### Including Post Creation Date
`{{ meta: created }}`
Will be replaced with the created date found inside `post.json`.
Additionally a `.created` css selector is applied to it to allow proper styling.
### Including Post Update Date
`{{ meta: updated }}`
Will be replaced with the updated date found inside `post.json`.
Additionally a `.updated` css selector is applied to it to allow proper styling.
### Including Post Tags
`{{ meta: tags }}`
Will be replaced with the tags found inside `post.json`.
Additionally a `.tags` css selector is applied to it to allow proper styling.
### Including external Code Snippets
`{{ snippet: name }}`
Will be replaced with the content of the file `name` found inside the `snippets` directory inside the posts directory.
`{{ scriptie: name }}`
Will be replaced with the content of the file `name` found inside the `snippets` directory and rendered via an [embedded
scriptie-talkie](http://thlorenz.github.io/scriptie-talkie-embed/).
**Example:**
Assume we have a post named mypost. Inside `./mypost` we created a `snippets` folder into which we copied `myscript.js`.
We can now include that in `./mypost/post.md` via `{{ snippet: myscript.js }}` or as a scriptie-talkie via `{{ scriptie:
myscript.js }}.
Remember to require and init scriptie-talkie:
```js
var domready = require('domready');
var embed = require('scriptie-talkie-embed');
domready(embed);
```
## Dog Provider
The dog provider assists you in serving your blog from a website.
It offers a number of functions to that purpose. Althoug all of them are explained here, you most likely will only need
the first four.
All mentioned callbacks have this signature: `function (err, result) { ... }`.
The below explanations assume that you required dog in your module via `var dog = require('dog');`.
### provideFrom
`dog.provider.provideFrom(fullPathToBlog)`
Call this before using any of the other provider functions to tell the provider in which directory your blog lives
(i.e., where the `blog.json` file is found).
### concatentateStyles
`dog.provider.concatenateStyles(callback)`
Concatenates all styles from `assets/styles` is is configured to include (see [includeStyles](#includestyles)) and calls
back with the resulting css.
### provideAll
`dog.provider.provideAll(callback)`
Gathers metadata of all posts that were published to your blog and attaches rendered html. Calls back with the result.
**Example Result:**
```
[
{ name: 'my-first-post',
metadata:
{ created: Sun Sep 16 2012 11:54:37 GMT-0400 (EDT),
updated: Sun Sep 16 2012 16:42:37 GMT-0400 (EDT),
tags: ['tag1', tag2'],
name: 'my-first-post',
title: 'Getting started' },
html: { ... }
},
{ name: 'my-second-post',
metadata:
{ created: Sun Sep 17 2012 11:54:37 GMT-0400 (EDT),
updated: Sun Sep 17 2012 16:42:37 GMT-0400 (EDT),
tags: ['tag2', tag3'],
name: 'my-second-post',
title: 'Getting started again' },
html: { ... }
}
]
```
### provideUpdatedSince
`dog.provider.provideUpdatedSince (when, callback)`
Same as [provideAll](#provideall) except only posts updated since `when`, which is a `Date` object, are included.
### copyImages
`dog.copyImages(fullPath, callback)`
Copies all images found inside your blog (i.e., in `assets/images`) to the `fullPath` given.
Calls back with an error if it failed or null if successfull.
### getAllPosts
`dog.provider.getAllPosts(callback)`
Calls back with a string array containing names of all posts that were published to your blog.
### getAllTags
`dog.provider.getAllTags`
Calls back with a string array containing all tags found in any of the posts that were published to your blog.
### getPostMetadata
`dog.provider.getPostMetadata(postName, callback)`
Calls back with metadata of the given post.
**Example Result:**
```
{ created: Sun Sep 16 2012 11:54:37 GMT-0400 (EDT),
updated: Sun Sep 16 2012 16:42:37 GMT-0400 (EDT),
tags: [ 'dog', 'tutorial', 'nodejs' ],
name: 'dog-tutorial',
title: 'Getting started with dog' }
```
### getPostHtml
`dog.provider.getPostHtml(postName, callback)`
Calls back with the rendered html of the given post.
### blog directories
Various functions return full paths to important directories inside your blog.
These are:
`dog.provider.getAssetsDir()`
`dog.provider.getImagesDir()`
`dog.provider.getStylesDir()`
### getStylesFiles
`dog.provider.getStylesFiles(callback)`
Calls back with a list of full paths of all styles included in your blog.
### printSummary
`dog.provider.printSummary`
Prints out a summary of your blog, including importand directories and published posts.
## Styling
Aside from including styles targeting `.blog-post` inside your sites styles file, you can also edit the styles included
with your blog inside `assets/styles`.
You also can include additional styles by dropping them into that folder and including them in your blog via
[includeStyles](#includestyles).
The `code.css` style is a [SyntaxHighlighter](http://alexgorbatchev.com/SyntaxHighlighter) theme and can be replaced
with any of the themes found [here](http://alexgorbatchev.com/SyntaxHighlighter/manual/themes/).
This will change the looks of your syntax highlighted code.
You may have to edit `code-fixes.css` as well in that case, since the styles in there are closely related.
## Examples
### Blog Only
Look at and play with [blog-only](https://github.com/thlorenz/dog/tree/master/examples/blog-only) to understand
better how to manage your blog and/or preview posts.
### Blog Site
Look at [blog-site](https://github.com/thlorenz/dog/tree/master/examples/blog-site) in order to get an idea on how to
use dog to provide your blog from a website.
### Tutorial
You can follow along with the [getting started tutorial](http://thlorenz.com/blog/dog-tutorial) to get a better
idea about how to use dog.
[](https://bitdeli.com/free "Bitdeli Badge")