The project documentation is not at all clear how to enable tags. about middleman-blog HOT 8 CLOSED

Doh, tags were part of a pull request. I never use them and it never got tested. Hopefully we'll have test cases of blog for 3.0.

I just pushed middleman-blog 0.1.4 with a fix. For this issue. If you can confirm it works, I'll address the documentation issue.

As an aside, the blog extension is basically just a bunch of code ripped out of my personal blog. If things don't make sense or the API is weird, let me know.

from middleman-blog.

My apologies for the delay. I can confirm that middleman-blog 0.1.4 does not fail in the way I described previously. I would appreciate the documentation updates.

Referencing this commit I find that the tags/blogging.html page has a 'Recent Articles' list below the silly h1 I added. I was a bit surprised at first, until I realized that source/layout.erb simply yields unless the page is a blog_article. Perhaps the project template could include some instructions for modification in the produced layout? The template almost certain to be modified beyond recognition and even modest guides would be helpful.

from middleman-blog.

Okay, first let me describe how I understand the setup in my head. If that makes sense, I'll write further guides along those lines. If not, then we can figure out a better structure going forward.

The middleman-blog extension ADDS basic blogging capabilities to an existing Middleman project. To do this, it requires a path to watch the contents of and consider those files the "articles." This path is specified by the "blog_permalink" setting which defaults to ":year/:month/:day/:title.html"

Any markdown files matching that path will be parsed for frontmatter (title, date, tags) and made available using "data.blog" object. Anywhere in your site, you can use this object to build links or summaries of the articles (for an archive page for example).

Again, to further separate blog pages from the rest of your site, they have their own "sub layout." The normal Middleman layout is used for all pages in the site (by default). Pages that are considered article pages, using the path setting above, are wrapped the a sub layout specified by the "blog_article_template" setting, which defaults to "article_template." There are some block/partial gymnastics in the default blog template to accomplish this.

At the end of the day, I'd love for the blogging extension to be able to form the basis of something like http://octopress.org/

I may port it from Jekyll some day, but I'm not sure there are enough hours in the day to maintain another piece of open source software,

from middleman-blog.

That is perfectly understandable. I think some slight distillation of that into the base template (or at least links to documentation) would be helpful.

Is the data object documented anywhere? I've learned about it indirectly, but I haven't a good idea of it's full content.

from middleman-blog.

Well, data is the namespace used by frontmatter, the data/ folder, the blog and the "remote data" extension. The first two are documented on the site. Blog probably needs more love. Remote data isn't really ready for prime time.

It's kind of an internal thing that handles "indifferent access" so the following all work:

data.blog.articles.first
data.blog[:articles][0]
data.blog["articles"].first.tags[0][:title]

Probably best to hide if from users and just start with "blog.articles"

from middleman-blog.

It's entirely possible I've not recognized the significance of what I've read, with regard to data. I have found these things:

• http://middlemanapp.com/guides/local-yaml-data
• http://middlemanapp.com/guides/individual-page-configuration

The data.page contains the front-matter, data any material in data/, yes? The contents of data.blog are still somewhat mysterious to me.

from middleman-blog.

Okay, definitely need to dive deeper into what's available and how to customize layouts/templates in the blog extension docs. There are only two objects in data.blog:

data.blog.articles
data.blog.tags

Which, have properties there is no way you could know about :-p

I'll probably hold off on updating the docs until 3.0 ships, but then I'll make sure blogging is much more fleshed out. I'm also adding generated code docs as another way of looking at the data.blog.articles object for those trying to figure it out.

from middleman-blog.

Docs for using tags on the master version of middleman-blog and middleman are up at http://beta.middlemanapp.com.

from middleman-blog.