README.md in brief-1.9.9 vs README.md in brief-1.9.11
- old
+ new
@@ -1,195 +1,73 @@
# Brief
[](https://travis-ci.org/datapimp/brief)
-Brief is a tool for building applications on top of collections of
-documents written in markdown.
+### Putting your writing to work
-Brief lets you define models very similar to how you would in
-ActiveRecord and Rails, but instead of rows in a database you are
-going to be working with files in a folder.
+Brief lets writers build applications on top of collections of markdown
+files. Brief lets you define different classes or types of documents, called
+`Model`s.
-### Getting Started
-```
-gem install brief
-brief --help
-```
+These models turn the documents into objects, which can be
+used to do things such as make API calls, or publish a blog post and
+send an email campaign at the same time.
-### Hypothetical Example
+### Turn documents into data
-```
-brief init my-cookbook
-cd my-cookbook
-brief generate model Recipe # View the DOCUMENTATION for what you can do with a model
-brief write recipe # => opens up your $EDITOR with an example recipe
-```
+The most basic way of combining writing with data, is through the use of
+YAML Frontmatter as metadata for the document. For example:
-Brief treats each markdown file as an active record style model object. It treats a folder of markdown files like a database.
-
-### How does it work?
-
-Brief takes a markdown file which looks like:
-
-```markdown
+```
---
type: post
-status: active
+status: draft
+tags:
+ - help
+ - ruby
---
-# An introduction to brief
-## Stop writing dead documents
+# This is a title
+## This is a subtitle
-Brief is a tool which lets you define different patterns of markdown
-headings (h1,h2,h3 etc). This lets you work with collections of your
-writings, and treat each document as a database.
-```
+This is the first paragraph.
-And turns it into data, not only using the metadata up top, but also the information
-contained in the structure of the document itself. The headings, subheadings, pretty much
-anything you could query from the HTML using CSS can be turned into key value pairs that you can work
-with and build applications on top of.
-
-With your enhanced writing, you can do things like:
-
-```ruby
-# Find all the posts which are active:
-posts = briefcase.posts.where(status:"published")
-
-# Get their titles, and subheadings:
-posts.map(&:title) #=>['An introduction to brief']
-posts.map(&:subheading) #=>['Stop writing dead documents']
-
-# Publish the post
-posts.first.publish()
-
-# Email the drafts to your editor
-posts.where(status:"draft").each &:mail_to_editors
+This is another pargraph.
```
-From the Command line we can:
+This YAML content at the top gets turned into data associated with the
+document.
-```bash
-brief publish posts
-brief write post #=> Opens your editor
```
+post = Post.new("/path/to/post.md")
+post.status # => 'draft'
+post.tags # => ['help','ruby']
+```
-This type of interactivity is made possible by the `Brief::Model`
+The YAML data is useful, but where the brief model system really shines
+is in the ability to extract data and metadata from the writing itself.
-### Documents as models
+Each `Model` prescribes its own specific structure, usually
+in the form of heading hierarchys (h1, h2, h3, etc). Any CSS selector
+can be used against the rendered HTML produced by the markdown. A
+model can define attributes that will be extracted from the writing, for
+example:
```ruby
define "Post" do
- meta do
- status
- end
-
content do
title "h1:first-of-type"
- subheading "h2:first-of-type"
- sample "p:first-of-type"
- end
+ subtitle "h2:first-of-type"
+ excerpt "p:first-of-type"
- actions do
- def publish
- update_attributes(status: "published")
- end
+ # parses YAML blocks inside the document
+ settings 'code.yaml', :serialize => true
end
end
```
-### CLI Tool
+### Getting Started
-Brief gives you a CLI called `brief`
-
-This lets you run some general commands, but also gives you an
-intelligent interface to work with your models. In the above example,
-we defined some actions.
-
-This will be available in the CLI:
-
```
-brief publish posts ./docs/posts/*.md
+gem install brief
+brief --help
```
-
-This will find all of the matching documents, turn them into `Post`
-models, and then run the publish method on them. You can make your
-models as advanced as you want:
-
-```
-define "Post" do
- actions do
- def submit
- update_attributes(status:"submitted to editors")
- mailer.send(:to => "jon@chicago.com", :subject => "Please review: #{ self.title }")
- end
- end
-end
-```
-
-### YAML Frontmatter
-
-Each markdown document can contain YAML frontmatter. This data will be
-available and associated with each document or model, and will also let
-you query, filter, and sort your documents.
-
-### CSS Structure Definition
-
-Since markdown renders into HTML, and HTML Documents can be queried
-using CSS selectors, we use CSS selectors in our model definition DSL so
-that we can isolate certain parts of the document, and use the content
-it contains as metadata.
-
-A real world example:
-
-```ruby
- content do
- title "h1:first-of-type"
- define_section "User Stories" do
- each("h2").has(:title => "h2",
- :paragraph => "p:first-of-type",
- :components => "p:first-of-type strong"
- )
-
- each("h2").is_a :user_story
- end
- end
-```
-
-This lets me turn a markdown file like:
-
-```markdown
----
-title: Epic Example
-status: published
----
-# Epic Example
-# User Stories
-
-## A user wants to do something
-As a **User** I would like to **Do this** so that I can **succeed**
-
-## A user wants to do something else
-As a **User** I would like to **Do this** so that I can **succeed**
-```
-
-into:
-
-```ruby
-{
- title: "Epic Example",
- status: "published",
- type: "epic",
- user_stories:[{
- title: "A user wants to do something",
- paragraph: "As a user I would like to do something so that I can succeed",
- goal: "I can succeed",
- persona: "user",
- behavior: "do something"
- },{
- title: "A user wants to do something else",
- paragraph: "As a user I would like to do something else so that I can succeed"
- }]
-}
-```
-
-And we can even go in the other direction.