Improve documentation

[itsMeBender]

Prologue

I had many problems, understanding the inner working of Metalsmith in relation to metalsmith-in-place and metalsmith-layout. Es-specially with the latest versions of those modules. My thoughts and the available documentation did not match each other.

Having Markdown .md content in combination with Handlebars .hbs as template structure. I couldn't make it work. Until someone set me on the right track.

Enter multiple file extension for a single file. Like as in index.md.hbs.

The README document, does describe it. But it wasn't clear to me. My mind is conditioned to think, only one file extension is allowed. I'm from the MS-DOS era.

Product enhancement

Add more explanatory examples in the README file, explaining the transformation of .hbs mark-up, in combination with .md mark-up, into a .html file.

Example:

If you write content using the Markdown .md mark-up. And using Handlebar mark-up to fix local URI's inside these Markdown content. For example ![Logo]({{ root }}/images/myCompanyLogo.jpg).
Then you need two transformations! This can be achieved by adding multiple files extensions to your content files. In the above case, use index.md.hbs.

The first processing step will be invoking Handlebars transformation .hbs for the file index.md.hbs. Then second wil be .md Markdown. Resulting in an index.html file.

[ismay]

I've opened the wiki's of both in-place and layouts, so that we can add usage examples there. Using the wiki's hopefully lowers the barrier of contributing examples a bit. So the todo would be:

• Add usage examples to the wiki
• Improve the readme

So let's discuss what to change exactly:

• Should we for example move the example that's currently in the readme to the wiki as well (and then link to the examples from the readme)?
• Also, what is currently confusing about the readme, or could otherwise be improved?
• Any suggestions about what use-cases to put in the wikis?
• Anything else missing or confusing, documentation wise?

Inviting @woodyrew @wernerglinka @Ajedi32 @axe312ger

[wernerglinka]

I have started the wiki on in-place with some of @ismay's suggestions for my blogpost. Please look at the introduction and edit as needed. A list of use cases underneath would be a way to do this. Let me know if this is ok.

[wernerglinka]

How should we deal with wiki articles that should be in both wikis? Should the layouts wiki just have a link to the in-place wiki?

[wernerglinka]

I added a couple of articles to cover Nunjucks templates. Added a section "Notes on Paths" at the end of Using Metalsmith in place with Nunjucks. I would appreciate if someone could review the section for accuracy.

[ismay]

Great work @wernerglinka

Please look at the introduction and edit as needed. A list of use cases underneath would be a way to do this. Let me know if this is ok.

I've edited the wiki and moved some of the writing to the readme (see #155), as I think the wiki is less discoverable and some of the information (like that you need to install jstransformers manually) is too important to be missed.

How should we deal with wiki articles that should be in both wikis? Should the layouts wiki just have a link to the in-place wiki?

Layouts has a lot more users, so I think it's a good idea to move examples that use both to the layouts wiki.

Other than that, I think it's good to keep the wiki focused on just examples, to prevent fragmenting the docs too much (I'm still considering where to put the explanation on the difference between layouts and in-place). I'm thinking it would be nice to have the wiki home page be a list of links to examples, with short descriptions under each link.

[wernerglinka]

I like your changes. Would be nice if someone could add an article for Handlebars, that seems to be quite popular... maybe @itsMeBender would be game ;-)

[ismay]

@wernerglinka I did quite some editing on the existing articles to get everything aligned. I tried to reduce the complexity in some of the examples, and just demonstrate some bare-bones use-cases that can be easily adapted.

However, a couple of things from the more complex examples are still useful to know, like not using a relative path when extending a layout with in-place, using partials, using a js build file, etc.

Maybe this part:

## Note on Paths
Files located in the src folder are transformed by Metalsmith into an object and thus are read from memory and not from disk. It means that Nunjucks cannot resolve relative paths inside of this folder. That's why the _extends_ tag in _src/index.njk_ must have a path that allows Nunjucks to find the file: `./layouts/layout.njk`. In this case `./` is the directory in which build.js is located in.

Files located outside the src folder are not transformed by Metalsmith and thus are read from disk. In this case, Nunjucks can resolve relative paths. That's why the include tag in _layouts/layout.njk_ has a relative path `partials/footer.njk`.

can go in the readme somewhere. Or in it's own example.

Also, I removed the notices about specific versions. I think the examples should be for the latest major versions of the plugins. Given that constraint we don't have to tie them to a specific minor or patch as we of course won't be making breaking api changes within the majors.

(I might've accidentally lost some history when editing the wiki btw. Apparently changing a title resets the history for that page. I assume it's still there when cloned though.)

[ismay]

I've also added the handlebars example btw.

[wernerglinka]

Hi Ismay,
Makes sense, now they are all conforming to a common format. But we have lost something. The biggest thing I learned when using only in-place was to use the extends tag in the source file to apply a template file and then to use a file path that points to the working directory. Once I understood that I was “over the hurdle”. I think we should add that back.
Werner

[ismay]

The biggest thing I learned when using only in-place was to use the extends tag in the source file to apply a template file and then to use a file path that points to the working directory. Once I understood that I was “over the hurdle”. I think we should add that back

Yeah definitely, I think that's important as well. I'll add it as a separate example, that way it'll hopefully be a bit easier to digest.

[ismay]

@wernerglinka I've added an example with nunjucks inheritance and your notes on paths with extends and includes, which I agree is quite important information. Let me know what you think: https://github.com/metalsmith/metalsmith-in-place/wiki/Advanced-example-with-nunjucks-template-inheritance

[wernerglinka]

Thank you @ismay I have added a Nunjucks variable into the source file to show that in-place will apply the template AND also make any variable substitution, e.g. {{ body_title }}.

[ismay]

@wernerglinka Cool, good idea 👍

[ismay]

I think that that's it. Any other use cases we need to cover for in-place?

[wernerglinka]

This is turning out well. We might want to ask some of the Slack users to review.

[ismay]

This is turning out well. We might want to ask some of the Slack users to review.

Done, asked in #general

[wernerglinka]

Thanks again for being so receptive to this. It will help new-comers. Now we can just point to the wiki ;-)

[ismay]

Thanks again for being so receptive to this. It will help new-comers. Now we can just point to the wiki ;-)

No problem at all, thank you for the suggestions and all the help! 😊🎉🎉

[ismay]

As a todo reminder, good suggestion by woody for another use-case to add:

• Using marked to render markdown, pass some options to marked to modify the rendering (show how engineOptions works)

https://github.com/jstransformers/jstransformer-marked
https://marked.js.org/#/USING_ADVANCED.md

[wernerglinka]

Ah yes, in my original article for Nunjucks and In-place I had listed the build.js file in which I defined a couple of filters that where passed to Nunjucks via the engineOptions. We lost that as well. Maybe we should add that back in, extending the Nunjucks environment has to be done via engineOptions now. I also have that covered in my blog post.

[ismay]

You’re right, I’ll add that back as a separate example as well 👍

[wernerglinka]

Having this as an separate example is probably the better approach. Easier to find…

…

On Jul 24, 2018, at 1:31 PM, ismay ***@***.***> wrote: You’re right, I’ll add that back as a separate example as well 👍 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#149 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAVIAKmQegjXcFl19mpZO5YPyvl6bJPBks5uJ2gdgaJpZM4VAgnC>.

[ismay]

I've added an example that uses marked with metalsmith's javascript api and shows how to enable syntax highlighting: https://github.com/metalsmith/metalsmith-in-place/wiki/Advanced-example-with-markdown-and-syntax-highlighting

It doesn't implement a custom renderer however, but I thought that from here adding further options should be doable.

[ismay]

Added the nunjucks custom filter example as well. Let me know if there's anything missing, or incorrect.

[wernerglinka]

Hi Ismay,
About the note of paths in the Advanced example with nunjucks template inheritance article.

I went back and reviewed the readme file for jstransformer-nunjucks and.. tada... there is now a root or path option that one can set to define the highest-level directory that can be searched for templates and macros. Config would look like this

const templateConfig = {
    engineOptions: {
        path: __dirname + '/layouts',
        filters: {
            toUpper: toUpper,
            spaceToDash: spaceToDash
        }
    }
};

Now we can use paths in relationship to /layouts everywhere.

This means that the section about path in the Advanced example with nunjucks template inheritance article is only true if the path is not defined. You may want to check this. It seems to work with my test setup.

[wernerglinka]

... and one more thing ;-)
I added a PR to jstransformer-nunjucks that allows the addition of Nunjucks extensions. This will result in this config:

const CaptureTag = require("nunjucks-capture");
...
const templateConfig = {
    engineOptions: {
        path: __dirname + '/layouts',
        filters: {
            toUpper: toUpper,
            spaceToDash: spaceToDash
        },
        extensions: {
            CaptureTag: new CaptureTag()
        }
    }
};

Hopefully, this will be merged soon so then we will have full control again over Nunjucks.

[ismay]

Yeah this issue is related to that I believe: jstransformers/jstransformer-nunjucks#10. Adding a path messed up my build in a couple of cases, which is why I'm now using this approach. But maybe things have changed in the meantime.

[ismay]

I think this is a good start. We can always add more examples to the wiki. Now on to do the same for layouts.