update docs and/or add metalsmith init for scaffolding site templates

[eddywashere]

I think adding an init option to the cli would help improve the ux around getting started with metalsmith and possibly help build a community of shared projects.

Examples:

metalsmith init .
# scaffolds out a metalsmith site in current directory

metalsmith init projectname
# same as above but creates site in a named directory

metalsmith init -t ghuser/ghrepo
# -t template option - creates a directory from a project template on github 

# ? other suggestions?

Current state of first time experience to metalsmith:

• via metalsmith.io
  • copy paste examples, npm install
    • result: non working example
  • point users to https://github.com/segmentio/metalsmith/tree/master/examples, assumes git clone, cd to right directory, npm install, make build
    • result: working example if all that went ok
• via yeoman, brunch, etc
  • npm install -g something-else, yo something-else option - result: hopefully that generated a metalsmith site
    • this is not only complicated for the user but also the person maintaining the project
• metalsmith project template on github
  • git clone, npm install, npm run?
    • easiest of all the options but metalsmith init will remove 2 steps from that process

Any thoughts or suggestions?

[RobLoach]

You might be looking for Khaos. Khaos uses Metalsmith to provide a scaffolding framework. Metalsmith tries to keep with the UNIX Philosophy and off-load additional functionality to plugins and other systems.

[ismay]

I've commented on this in another issue as well, but I've started a collection of metalsmith-boilerplates. My purpose is to create simple boilerplates, which might solve the problem @eddywashere is trying to address.

It's pretty minimal right now, but I'll be adding more examples soon. Also, I'd love some help in the form of pull requests or critique!

[ianstormtaylor]

I agree with @RobLoach, see #205 (comment) for discussion.

[ismay]

Using Khaos sounds like a good idea. When I have the time I'll refactor my examples to khaos templates.

[ninjasort]

I have to +1 @eddywashere on this. I don't think it makes sense to off-load so much functionality to plugins and other systems. The CLI in hexo and jekyll provide a nice set of commands to interact with your project, without this I think we're missing a really important part of this workflow. Why would it make sense to off-load this if metalsmith has a CLI of it's own already?

[Ajedi32]

@cameronjroe I guess the real question here is, what features might we want to include in a tool like this that aren't already available in a dedicated scaffolding tool like Khaos?

The way I see it, putting this functionality in the Metalsmith CLI has a few potential advantages:

1. It's slightly easier to set up (e.g. npm install -g metalsmith-cli gets you everything you need, vs npm install -g metalsmith && npm install -g <other_tool>)
2. We can include metalsmith-specific functionality that wouldn't make sense to put in a third party tool (though I'm currently unsure of exactly what this functionality might be)

And it also has disadvantages:

1. We have to develop and maintain a separate tool
2. Users need to learn a Metalsmith-specific CLI tool instead of a more generic one that they can use for more than just Metalsmith projects.

[ninjasort]

@Ajedi32 I think to address that question we have to think of the lifecycle that one would go through to create a static site. Ideally that includes at least the following:

[scaffold] -> [plugin customization] -> [development] -> [env builds] -> [deploy]

If metalsmith is being used for building websites, it would ideally address this type of lifecycle. Either way, someone is going to have to do these things to build and deploy a website. A CLI can be third-party or batteries included, but I'm a fan of the latter.

[ninjasort]

I think another important point to highlight here is that most people are probably not looking to "develop" a static site generator in the process of building a static site. If there's so many small packages to combine manually with no high-level framework, it becomes sort of a burden to use and someone may chose to go with hexo or jekyll for that situation. I guess it really depends on the benefits of merely separating packages over creating a framework that includes those separated packages.

[Ajedi32]

I think as long as we explain the use of Khaos in our documentation and don't need any metalsmith-specific functionality in our scaffolding tool there's not actually a big difference between "third-party" vs "batteries included". It's just one extra installation step, and a slightly different command to use to generate the scaffold.

Or were you suggesting that the metalsmith CLI provide a complete solution for customizing plugins, developing the site, and deploying to production? Hmm...

You know, the more I think about this the more I'm starting to agree with @ianstormtaylor and @RobLoach about keeping these things in separate tools. Most of this sort of functionality is in no way specific to Metalsmith, and Metalsmith's highly unopinionated nature doesn't lend itself well to metalsmith-specific tools for most tasks (configuring plugins, generating new blog pages, etc).

Or, to make that more concrete

• Creating a new project - Grab a set of files from a template. Not Metalsmith specific. khaos create <template> <project> && cd project && npm install
• Installing plugins - npm install --save <plugin>
• Configuring plugins - Difficult to automate. Different plugins require completely different options. Easily done by manually editing JSON (or JavaScript, if you're not using metalsmith.json)
• Development
• Scaffolding new pages in a project - Difficult to automate. Works completely differently depending on what plugins you have installed and how your project is laid out
• Builds - Potentially different for every project, but should only be one command. npm run build, make, grunt build, metalsmith.
• Deploy - It's just a directory of static files. Pick a tool, any tool!

Now that isn't to say that I'm against the "batteries included" approach either. I think it is possible to get the best of both worlds to some extent, though you're not going to be able to automate things to the degree that (for example) Jekyll does without becoming a lot more opinionated first.

So how can we make Metalsmith more friendly for users who want things to "just work"? Well, I think scaffolding actually gets us about 90% of the way there. Why? Because it's easy to include third-party tools and documentation as part of the scaffold. Want a build tool? Make the scaffold include a Gruntfile, and have the README tell users to build the project with grunt build. Want a way to deploy? Include netlify-cli in the devDependencies, and run it via. npm run deploy.

Not only is this easier to do than trying to build a fully integrated solution ourselves, but it also doesn't lock users into using any one specific tool for doing their builds or deploys. Want to switch to Gulp? Go right ahead! Prefer to deploy to GitHub pages? Do it!

Can you think of any downsides to this approach, or advantages of an integrated solution that it might miss out on?

[ninjasort]

I took a closer look at Khaos and I think your points are valid. An alternative approach might be to separate the metalsmith CLI to it's own repo and have opt-in scaffolding leveraging Khaos along with maybe a few other commands for running metalsmith with multiple environment flags. Thoughts?

npm install -g metalsmith-cli

Scaffold

metalsmith new [khaos-args]

Develop

metalsmith server -p 3000 // watch source directory for changes and auto-build with browser-sync

Deploy

metalsmith build -e prod

metalsmith.js

import Metalsmith from 'metalsmith'
import plugins from './metalsmith-plugins'

let env = Metalsmith.env
let m = Metalsmith(__dirname)

m.use(...plugins)

if (env.prod) {
   m.build((cb) => {
      // prod built
   });
}

Also, I think it would be helpful to be able to run builds on a metalsmith.js file as well as metalsmith.json, this way you enforce some convention as part of the CLI usage.

Overall, you don't need the CLI with metalsmith unless you're currently using metalsmith.json, with this approach one could leverage metalsmith as is, or install the CLI in addition to get the convention-driven scaffolding, development, and deploy features.

[ianstormtaylor]

@Ajedi32 I agree with you there! 👍

[ismay]

The reason I chose metalsmith is because of how unopinionated it is, and because it basically allowed me to build exactly what I want in a static site generator. I'd hate to lose that freedom by automating things too much.

But I've also noticed that new users are sometimes struggling to understand it all. I think that if we're going to go the route of the khaos templates (which I'd prefer), they should be at a centralized and highly visible location. Indexed on metalsmith.io for example. Otherwise it'll be too scattered and still won't help new users.

And of course we'll need to decide how far in depth we want to go with the templates, and preferably have enough of them to accomodate most use cases. Then hopefully that'll attract some attention and build momentum to generate more.

[Ajedi32]

Just stumbled across this article that is surprisingly relevant to what we're discussing here right now:

https://medium.com/@ericclemmons/javascript-fatigue-48d4011b6fc4

[RobLoach]

metalsmith new [khaos-args]
metalsmith server -p 3000 // watch source directory for changes and auto-build with browser-sync

I still believe these should live outside of Metalsmith. Metalsmith is simple, it takes a directory, does some stuff with it, and outputs it to another directory. There are better solutions out there for boilerplating and serving. Nothing is stopping you from putting together cameronsmith-cli and sticking the tools you find best there 😉 .

[eddywashere]

@ianstormtaylor I think a bigger win is a better getting started page, which I think we can agree is the current website. Currently:

• there is not a primary call to action
• the example code blocks posted are out of context
  • examples link is hard to find
  • code in there doesn't look like the home page examples
• it's difficult to share a link to this project without walking people through setup/config or sending a blog post along with a github repo

Something like the following would be really great:

mkdir project
cd project
touch package.json
mkdir src templates
touch build.js src/hello.md templates/default.html

package.json

// example package.json contents, with npm script for running server/build/etc

Install dependencies with npm install.

show example contents for build.js, src/hello.md, and templates/default.html.

With all of that, someone brand new to this project would have a straight forward approach to working with metalsmith. I would submit a pr for this but I don't know if it would be accepted.

[ninjasort]

Ah, I might just need to switch to hexo here. Oh well. :/

[RobLoach]

I propose a new project named mentalsmith.... Brings all of this together in a mentally sane way 😉 .

[webketje]

The way forward for this with the least required maintenance is:

• Better docs (being worked on atm), importance of examples. There is a CTA now for example.
• a working npx metalsmith shortcut
• Template GH repositories ("Use this template" => forks & displays 'generated from")

I'm against including scaffolding features in core because it falls for the pitfall of trying to automate initial setup while the bulk of the work is done during subsequent maintenance. It's ok if the initial setup requires a bit of discovery mode. I'm leaving this issue open as it contains interesting discussion points that I will revisit later to add to docs/ get inspiration