deardesi.js/README.md

133 lines
4.6 KiB
Markdown
Raw Normal View History

2015-01-24 02:19:10 +00:00
<!--
2015-01-22 02:53:57 +00:00
Not a Web Developer?
====================
2015-01-22 02:54:25 +00:00
You're in the wrong place. **Go to <http://dear.desi>** and follow the instructions there.
2015-01-24 02:19:10 +00:00
-->
Did you mean to come here?
==========================
If you're a normal person interested in *Desi, the DIY blog platform for normal people*,
you might have meant to go to [DearDesi](http://dear.desi) instead.
Otherwise, if you're a cyborg, wizzard, or web developer: carry on.
2015-01-22 02:53:57 +00:00
2015-01-13 10:37:21 +00:00
Dear Desi
=========
2015-01-11 04:58:49 +00:00
2015-01-24 02:19:10 +00:00
These instructions cover the command line only.
2015-01-11 04:59:40 +00:00
2015-01-24 02:19:10 +00:00
If you want instructions for the web interface, head over to [DearDesi](http://dear.desi).
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
Command Line Install (for developers)
--------------------
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
This assumes that you already have `git` and `iojs` (or `node`) installed,
otherwise see [iojs-install-script](https://github.com/coolaj86/iojs-install-script)
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
```
npm install -g desi
```
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
That was easy
2015-01-24 02:19:10 +00:00
Quick Usage
-------
2015-01-24 02:19:10 +00:00
* desi init -d ~/Desktop/new-blog
* pushd ~/Desktop/new-blog
* desi post "my first post"
* desi build
* desi serve
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
<http://local.dear.desi:65080>
**Note**: both through command line and web you need `site.yml` and `authors/xyz.yml` configured in order to create a post (as well as build).
The post commands output the location of post in various formats.
Initialize your blog (step 1)
--------
You can do this 3 ways:
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
1. Create a new blog with `desi init -d ~/Desktop/blog`
2. Clone the seed project and themes yourself
3. Clone the seed project and import your posts and themes
### Automated (desi init)
2015-01-13 10:37:21 +00:00
```bash
2015-01-24 02:19:10 +00:00
# initialize (and or create) a blog directory
desi init -d ~/Desktop/blog
# initialize the current directory
pushd ~/Desktop/blog
desi init
2015-01-13 10:37:21 +00:00
```
2015-01-24 02:19:10 +00:00
Note that you cannot initialize a directory that is already in use
(where 'in use' means has at least one non-dotfile).
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
### Manual (clone yourself)
There are a number of themes available at <https://github.com/DearDesi>,
just look for ones with 'theme' in the description.
```bash
2015-01-13 10:37:21 +00:00
git clone git@github.com:DearDesi/desirae-blog-template.git ~/my-desirae-blog
pushd ~/my-desirae-blog
2015-01-24 02:19:10 +00:00
git submodule add git@github.com:DearDesi/ruhoh-bootstrap-2.git themes/ruhoh-bootstrap-2
2015-01-13 10:37:21 +00:00
```
2015-01-24 02:19:10 +00:00
You will need to make sure that you have some details about your theme in `config.yml`.
Basically that means that you specify a [`datamap`](https://github.com/DearDesi?query=datamap)
and which defaults for a `page` and `post` in the `layouts` folder.
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
Just open it up, it'll make sense.
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
### Migrate (import another blog)
2015-01-24 02:19:10 +00:00
Obviously this is a little different for everyone, so here's what I'd recommend:
2015-01-24 02:19:10 +00:00
1. start by following the Automated procedure above
2. copy over your posts/articles folder(s)
3. edit `config.yml` to add a config with a permalink with your collections (posts, articles, essays, whatever you call them)
4. skip ahead to the *Setup your blog* section and make sure your `site.yml` and `authors/xxx.yml` are correct.
5. run `desi build -d /path/to/blog` to test if there are any issues with your existing yaml
* if there are, you can take a look at the [normalize](https://github.com/DearDesi/desirae/blob/master/lib/transform-core.js#L72) function and perhaps hand-edit a few things (and when you're ready, you can [register your transform](https://github.com/DearDesi/deardesi/blob/master/bin/deardesi.js#L28) for collections.
6. Now copy over your theme and set it to be the default in `site.yml`
7. build again. Your site probably won't look right:
* look for stuff like `urls.base_url`, `host`, `page.url` that might have an extra `/` at the beginning or end or be named slightly differently.
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
See <https://github.com/DearDesi/desirae/blob/master/GLOSSARY.md> for disambiguation about the meaning of terms in Desi.
2015-01-24 02:19:10 +00:00
Setup your blog (step 2)
------------
2015-01-24 02:19:10 +00:00
1. Create an authors file in `authors/YOUR_NAME.yml` and model it after [this example](https://github.com/DearDesi/deardesi/blob/master/example/authors/johndoe.yml)
* You don't need to use all of the fields (your template might not even support them all)
2. Create a site file as `site.yml`, similar to [this example](https://github.com/DearDesi/deardesi/blob/master/example/site.yml)
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
**Important Things**
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
* `site.yml.base_url` - the point of ownership (usually blog.example.com or example.com)
* `site.yml.base_path` - where the blog is "mounted", relative to the `base_url` (usually `/` or `/blog`)
* `authors/me.yml.name` - most templates use this
* `authors/me.yml.email` - and this
* `authors/me.yml.twitter` - and this
2015-01-24 02:19:10 +00:00
Build your blog (step 2)
------------
2015-01-13 10:37:21 +00:00
2015-01-24 02:19:10 +00:00
The build *will* fail if you don't have `site.yml` and `authors/johndoe.yml` configured.
```bash
desi build -d /path/to/blog
desi serve -d /path/to/blog
2015-01-13 10:37:21 +00:00
```
2015-01-24 02:19:10 +00:00
Now open up your evergreen browser to <http://local.dear.desi:65080>