assemble / assemble Goto Github PK

Write markdown directly inside any HTML file, handlebars or other template and compile it to HTML

In particular, github flavored markdown would be best, since github seems to have the most active and rich version of markdown.

npm owner add doowb assemble

This will allow partials and handlebars tags to be more flexible and DRY. The page title is a good example:

<h1>{{page.title}}</h1>

For which the yaml front matter is:

---
page:
  title: Hi! I'm the page title!

---

Now, if you are visiting a theme, you might want the name of the theme to be the page title, so you could change the template on every page, like this:

<h1>{{theme.name}}</h1>

and this:

---
page:
  title: 
theme:
  name: Bootstrap

---

But a better way to do it is to keep the template the same, like this:

<h1>{{page.title}}</h1>

and process templates in yaml front matter like this:

---
page:
  title: {{theme.name}}
theme:
  name: Bootstrap

---

The yaml front-matter shouldn't require a specific template engine. Split that out to make it default to use in all assemble builds.

see: https://gist.github.com/4692922

channeling @doowb

"Adding ability to specify the layout template from within the page yaml front-matter. Also able to use underscore templates to expand config values from within grunt"

After trying out several different project configurations and trying to optimize build targets, I think this makes a lot more sense:

• require only path to layouts folder. it would probably be better to have the path to the layouts folder set in paths.json or as a global option somewhere (config.json, defaults.json or whatever the file should be called). Then maybe allow user to override that with a custom path inside a grunt target or the config for a specific project
• allow layout to be determined in yaml front matter, requiring only the name of the layout. for now, we can hard wire all layouts as .mustache files, so just the file name would suffice (if it's better to include ext I don't feel strongly about it):

---
layout: blog-post

---

• allow overriding the layout specified in the yaml front matter with a layout specified in a page configuration, like this:

Example pages.json / scaffold.json (not sure what we should call that yet)

{
    "page": {
        "layout": "some-layout"
    }
}

• allow empty value for layouts

---
layout: 

---

or

---

---

@doowb you should create a clean task to clean out the app folder, or any files that change names or move folders will leave junk behind

multiply{{template1}} * {{template2}}

I don't know what the best syntax is, but this would be awesome. It would also be great with underscore templates.

This throws an error

---
title: Example: Home Page

---

Such as automatically compile with the name and path of a file, like:

<!-- this file lives in {{ assemble.path }}/{{ assemble.file-name }} -->

which would render to:

<!-- this file lives in pages/legal/terms-of-service.html -->

Currently, you have to do this:

<link href="{{assets}}css/styles.css">

It's more intuitive to require a forward slash after {{assets}}:

<link href="{{assets}}/css/styles.css">

I am trying to install assemble from npm:
npm install assemble --save-dev

but node_modules/assemble contains only README.md and package.json files

Also I tried to install it from git:
npm install git://github.com/sellside/assemble.git --save-dev
but get an error when I try grunt assemble, I get an error: Error: Cannot find module 'lodash'

So I installed lodash... than js-yaml, marked and highlight.js
Then it worked out!

(issue was moved over from generate repo)
Determine if something is happening in one of the partial/page loading sections that is over writing the title variable and cause it to be an object instead of a string variable.

e.g.

page.title
site.name etc.

This is what I do today, using currency as an arbitrary example. I presently have the object currencies setup with an array of currencies in site.json like this:

// site.json
{
  "brand": "themestack",
  "currencies-enabled": true,
  "active-currency": "USD",
  "currencies": [
    {
      "ISO": "USD",
      "VAT": "",
      "modifier": ""
    },
    {
      "ISO": "CAD",
      "VAT": "",
      "modifier": ""
    },
    {
      "ISO": "EUR",
      "VAT": "",
      "modifier": ""
    }
  ]
}

And the data is used like this:

{{#if site.currencies-enabled}}
  <ul class="dropdown-menu">
    {{#each site.currencies}}
      {{> currencies }}
    {{/each}}
  </ul>
{{/if}}

If possible, I would like to externalize the array of currencies to another file, currencies.json, and have that automatically recognized by the compiler so that no changes are required in the handlebars templates. So markup and templates would stay the same, but the json would change to:

// site.json
{
  "brand": "themestack",
  "currencies-enabled": true,
  "active-currency": "USD",
  "currencies": "currencies.json"
}


// currencies.json
[
  {
    "ISO": "USD",
    "VAT": "",
    "modifier": ""
  },
  {
    "ISO": "CAD",
    "VAT": "",
    "modifier": ""
  },
  {
    "ISO": "EUR",
    "VAT": "",
    "modifier": ""
  }
]

Best place to document this is in ./docs/options.md I think. I already got a good head start on this, so just look through it and edit whatever you want. I might merge a couple docs, but for now it helps to keep them separate

https://github.com/sellside/assemble/blob/master/docs/engines.md

I'll create some placeholders for adding engines, then @doowb it would be good to have you fill in some details (very brief).

IMPLEMENTED IN ASSEMBLE v0.6.0! Any engine can be registered like:

assemble.engine('swig', require('engine-swig');

Templating engines under consideration. Comments/feedback encouraged.

• mustache
• handlebars (website)
• underscore (website)
• Nunjucks . Seems to share a lot of similarities with liquid, from the docs "It is a direct port of the Python-powered jinja2 templating engine and aims to be feature-complete with jinja2."
• Eco
• dust (website)
• ejs
• haml (website)
• haml-coffee (website)
• hogan (website)
• jade (website)
• swig (website)
• liquid.js

If you would like an engine added to the list, please make a comment on this issue so I can add it to the list for consideration.

YAML is more readable sometimes. would be nice for a user to be able to arbitrarily add .json or .{yaml,yml} files as needed.

options: {
     data: [ 'config/site.json', 'config/content.yml', 'src/data/grid.json' ]
}

Add more attributions and cross-references to other docs.

https://github.com/sellside/assemble/blob/master/docs/helpers.md

Jekyll does this currently. The way it works is you can create a very simple layout that has only the head and body tags, for example. Other layouts will then use that layout as a base, but with additions such as a navbar, footer etc..

For example:

base-layout.hbs

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Document</title>
  </head>
  <body>
    {{> body }}
  </body>
</html>

kitchen-sink-layout.hbs

---
layout: base-layout.hbs

---
{{> navbar }}
{{> body }}

http://paularmstrong.github.com/swig/

pull requests welcome on this too ;-) !

need to be able to set options for yaml, marked, handlebars directly in the assemble task. the native options of those plugins should be made available somehow. we can talk this through to come up with a tactful way of doing this

Useful if you have a static site and organize your pages into folders.

So, for example in the navbar on the index.html page, you would just add something like the following to the href attr for the link to the contact page:

{{assemble.path.relative}}/contact-us.html

and then the helper would would insert the correct path to that page, so you wouldn't even really need to think about where the other files are located, as long as the file names are unique.

Or, if you had two files with the same name you could do something like this:

{{assemble.path.relative}}/domains/search.html

and

{{assemble.path.relative}}/themes/search.html

so the helper would use the folder and the file name to reconstruct the path. In other words, in cases where you will have duplicate file names, you can add as many folders before the file name as you need for the file name to be recognized as unique. Make sense?

or it could be done with underscore

I think template inheritance should work like this:

• "section" blocks are used to create the default content
• "extend" blocks inherit "section" blocks

Layout: default.hbs

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>{{ title }}</title>
    </head>
    <body>

        {{#section "header"}}
          <div class="page-header">
            <h1>Welcome to our site!</h1>
          </div>
        {{/section}}

        {{> body }}

        {{#section "footer"}}
          <script src="assets/jquery.js"></script>
          <script src="assets/bootstrap.js"></script>
        {{/section}}

    </body>
</html>

Page: some-page.hbs

---
title: About Us
layout: default.hbs

---
{{#extend "header"}}
  <div class="page-header">
    <h1>{{ title }}</h1>
  </div>
{{/extend}}

<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>

{{#extend "footer"}}
  <script src="assets/jquery.js"></script>
  <script src="assets/bootstrap.js"></script>
  <script src="assets/other-script.js"></script>
{{/extend}}

Note also that the extend blocks don't have to be in any particular order. They could be like this:

---
title: About Us
layout: default.hbs

---

<!-- this content would go in the {{> body }} -->
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>

<!-- this content would replace the head section -->
{{#extend "header"}}
  <div class="page-header">
    <h1>{{ title }}</h1>
  </div>
{{/extend}}

<!-- this content would replace the footer section -->
{{#extend "footer"}}
  <script src="assets/jquery.js"></script>
  <script src="assets/bootstrap.js"></script>
  <script src="assets/other-script.js"></script>
{{/extend}}

In the doc I don't see that layout is required. But without it, I ran into an error:

Warning: EISDIR, illegal operation on a directory Use --force to continue.

Maybe a clearer error message ?

see https://gist.github.com/4692922 and features #27 and #26

The links in the gh-pages are pointing to the sellside org.

Not a priority, but it would be pretty awesome. There are two ports that seem to be the best options (might be others):

• liquid.js
• node-liquid

Other repos:

• node-liquify
• liquid.js (built on node-liquify)

Partial support for liquid-node here: https://github.com/tchype/node-liquid-partial

https://github.com/sstephenson/eco