-
Notifications
You must be signed in to change notification settings - Fork 627
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
update docs and/or add metalsmith init for scaffolding site templates #153
Comments
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. |
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! |
I agree with @RobLoach, see #205 (comment) for discussion. |
Using Khaos sounds like a good idea. When I have the time I'll refactor my examples to khaos templates. |
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? |
@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:
And it also has disadvantages:
|
@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. |
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. |
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
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 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? |
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?
Scaffold
Develop
Deploy
metalsmith.js
Also, I think it would be helpful to be able to run builds on a Overall, you don't need the CLI with metalsmith unless you're currently using |
@Ajedi32 I agree with you there! 👍 |
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. |
Just stumbled across this article that is surprisingly relevant to what we're discussing here right now: https://medium.com/@ericclemmons/javascript-fatigue-48d4011b6fc4 |
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 |
@ianstormtaylor I think a bigger win is a better getting started page, which I think we can agree is the current website. Currently:
Something like the following would be really great:
// example package.json contents, with npm script for running server/build/etc Install dependencies with show example contents for 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. |
Ah, I might just need to switch to hexo here. Oh well. :/ |
I propose a new project named |
The way forward for this with the least required maintenance is:
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 |
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:
Current state of first time experience to metalsmith:
Any thoughts or suggestions?
The text was updated successfully, but these errors were encountered: