metalsmith
metalsmith copied to clipboard
metalsmith
Lack of Official Documentation, why?
Hi, I am new to static-sites and I have already tried a few but I find metalsmith with its use of plugins as npm packages, quite fascinating. Even though most of the work here is plugin based, I am disappointed by the lack of one single documentation which can at least guide a new comer, like me, thoroughly.
Yeah, documentation has been something we've been talking a lot about lately.
For now, your best bet is here: https://github.com/metalsmith/metalsmith#resources
:+1:
Lack of documentation is a kind of a bad joke nowadays.
For example: there is a "thing" called: "metalsmith.json"... 99,9% undocumented.
How am I supposed to use this? Are there any examples?...
Are there any examples?
There's a whole directory full of examples here: https://github.com/metalsmith/metalsmith/tree/master/examples
@Ajedi32 These examples are undocumented and mostly just useless.
Short question: How can I use settings defined in metalsmith.json when I run metalsmith programmatically? Is this for command line use only? Or what?
Do you really think people want to read code just to run at least damn simple "hello world" site?
Your website is a kind of a bad joke too:
An extremely simple, pluggable static site generator.
Yeah... right...
Here’s what the simplest blog looks like…
ORLY?
Is this so hard to mention that this is probably "simple" for js/node developers?
Where am I supposed to put this code? What command to use to run this sh*t?
I had to use some magic power to figure it out because is NOT mentioned on your website at all.
See this video please. I cannot agree more. Your website and documentation is "troll documentation": https://www.youtube.com/watch?v=e3hkjeM_DUQ
@amandeepmittal Harsh truths can help you grow. Do you really think that you solved problem in this way?
metalsmith.json is only read by the Metalsmith CLI. There's currently no API exposed in Metalsmith for building a Metalsmith object based on that file (though I certainly wouldn't be opposed to adding one).
If you've got any specific improvements you'd like to make to the documentation, feel free to send a PR (either to here, or to the repo for the website). A lack of documentation is exactly why this issue exists in the first place. If you have any questions, feel free to ping me here or ask in the Metalsmith Slack channel.
@amandeepmittal If your intention was to unsubscribe from this issue, there's a button for that over on the right :arrow_upper_right:. Missing docs is still definitely an issue Metalsmith has, so I'd rather leave this open for now.
- IMHO documentation should mention directly what these pieces of code on homepage are for.
I understand that you expect that only people with some knowledge read them. However keep in mind that static generators are tools mainly for front-end developers. They often have no clue about node and server side scripting at all.
For you it's quite obvious what to do with this code. Thing is that you don't build website and manual for yourself.
- On your website there are some pieces of code... you cannot run this code directly with CLI. It's not mentioned on homepage, where to use this code and what to do to execute this code. JS/Node knowledge is required.
Then we have some info how to use CLI with metalsmith.json. Now I know that these things do not work together.... while this behavior is not mentioned in readme.
@Ajedi32 My intention wasn't to leave this issue, but I thought the issue is quite old and still there is no work on documentation, may be you guys aren't interested. But looks like you are aware of and hopefully working towards it. Btw, I recently pulled a request to update "awesome-metalsmith" resources which is also a bit outdated and some new resources have come up and would be very helpful to the new users of metalsmith.
@marcinant Martin, I did not mean to offend you. And if you are offended than it's your fault. You do not know if someone is knew to some thing or some community and doesn't know how things work. At least learn some etiquettes on how to respond, and if you think your ego is bigger than yourself then shut your mouth.
Yeah, the home page definitely is missing some important details on how to run the provided code. Actually it seems that right now it's more of a demo to show off how Metalsmith feels than a full-on "getting started" guide. I'd love to see a bit more detail added to the site homepage and README.
In addition, proper docs would be an opportunity to show off Metalsmith's capabilities - the documentation and the code to build it would be a great example of what Metalsmith can do.
I just got my hands on metalsmith, as it was listed in one of the best static site generators, and maybe the most common used when talking about nodejs.
My most important question is: How come there is no SIMPLE EXAMPLE to start with?!
This is unbelievable! Yeah I've checked the examples page and I used the jekyll sample, and do you know what it does? It exports me four html files that has nothing in between! It's just a page for each post, and no index page to list them all! Well thank you for that, it was exactly like jekyll!
Now I know why this library is not that much used and spread. It might be very powerful, but lack of any kind of documentation and examples is killing me. You know, people are using this kind of software because they want to get things working fast. I'm writing this after hour and a half of just trying to build anything that will show up. There's an article about how to build blog post, which is from May 2015, and uses metalsmith-templates, which is now deprecated. And it uses code instead of metalsmith.js for building, BUT metalsmith-layouts does not have any kind of examples using code!
I know I can figure this out, maybe after a day or two. But this is now how open source projects go. I don't know why you don't want to put a little effort on this, as it's now useless for me.
I'm sorry for the really negative comment, but I'm just tired of trying new things that are so hard to use that waste more time than hacking it by myself.
@fourpixels Thanks for your feedback, I guess? As you can see from this thread we are already aware of the issue and will address it as soon as one of us has the time and will to do so. Further complaints aren't really constructive.
I don't know why you don't want to put a little effort on this
Who says we don't? I know I certainly do, but as with many (most?) other open source projects none of us are paid to work on Metalsmith, so the time we're able and willing to spend on issues like this is rather limited.
@fourpixels I very much agree, there is a lack of documentation and I think it's the biggest issue with Metalsmith.
There are Community Driven tutorials but as you can see, it's not had a lot of contributions and hasn't been very discoverable from my experience in the community. There is a starting out with templates tutorial that should help you. We also have a Slack channel which is relatively active for any questions or problems you might have.
For moving forward, I think it would be good to re-work the main metalsmith.io index page and add getting started tutorials.
@Ajedi32 I don't understand how you want to continue developing/supporting this project, and you do not have time to MERGE a PR for about four months. Come on, this doesn't sound much professional..
@woodyrew I agree with that. I've written that nasty comment just because I see that I could jump on and try to help with the docs, but there's no one to even merge what I'll do. It turns out there's no reason doing it, you know? It just makes me feel like there's no easy way to start doing it, there's no easy way contributing to the project, there's no reason for me to continue trying. For that hour and a half (and even less) I was able to setup blog-like static page, with generation, deployment, changed template engine, custom plugin and custom theme all along with the main competitor of this project. I'm sure Metalsmith might be way more powerful, but I don't have time diving into it for days.. I wish I could!
Good luck!
@fourpixels That particular PR is going to take a bit of work to get merged (as part of the merge, I plan to address some grammatical and structural issues I have with it in its current form); it's not as simple as just clicking the button, otherwise I would have done so already. After I fix the deployment to metalsmith.io (metalsmith/metalsmith.io#149), addressing that PR is my next priority.
In theory, despite the lack of documentation, one could look at the source code. But the comments in the source code are terrible. They are prime candidates for a presentation of "here are example of useless source code comments." For example, for source(), "Get or set the source directory". We effing knew that. What is the source directory? How is it different than the "root directory"? What is the default?
@MorganConrad I just printed out the results of the metadata in a custom plugin to figure it out. But that's neither here nor there. I think a person with no javascript experience, or no programming experience should be able to use the software. As things are I'm not sure what the intended user is supposed to be. Maybe people with Javascript experience? Even so I think metalsmith is nice for what it does.
Over two days I set up a blog for my girlfriend. It works, but that was quite a learning curve.
Maybe when the cli gets split out the documentation can be improved.
I've added a Basics of Metalsmith page to the wiki. The two main points that I thought might be helpful are:
- Clarifying what (and how little) it actually does before adding in any plugins.
- Clarifying the API vs CLI use cases, with really simple examples.
By all means, please get your wiki on and revise, edit, cut, copy, and generally improve as desired. Hopefully it helps get the ball rolling. I might work on the simplest possible "How do I even custom plugin?" page next, if it helps, walking through something like the drafts example to bring up underlying principles.
@lukehler Also I'm wondering if it would be too much to add --init to the metalsmit cli. Like metalsmith --init which would generate the metalsmith.json, prompt the user for information to place there, and present sensible defaults for plugins like the markdown plugin.
Though that might be worth posting in a whole other issue.
@lukehler Thanks, that's a really nice explanation. Perhaps it'd be a good idea to add some of that information to the Metalsmith website. Feel free to submit a PR to the metalsmith.io repo if you notice anything on that site you think could be improved.
I've been considering adding a few more pages to that site for a while now, but I haven't gotten around to it yet.
@Ajedi32, this project is awesome, thank you for putting time and effort into it. It solves a very specific and common need in a simple and extensible way and it just what I was looking for. Your efforts are very much appreciated.
With the efforts that have been poured in since 2021 on revamping the docs AND adding more meaningful comments to the source code AND me being acutely aware of the importance of good documentation, I believe this issue can be closed.
