Custom template override

[BrianWendt]

I think it would be a good idea to be able to override templates.

I propose adding an option
-t --template path to directory containing Embedded JavaScript (ejs) templates
jsonschema2md -o docs/reference -t docs/templates

The module would look first for the template ejs file in the given directory and fallback to the default template found in @adobe\jsonschema2md\templates\md.

This would provide the ability to override specific template includes giving users more control over their documentation.

I believe this would require some changes to the following

• lib/markdownWriter.js
• lib/readmeWriter.js
• lib/schema.js (edit: I missed this in my initial evaluation)
• templates/md/array-types.ejs
• templates/md/property.ejs
• templates/md/pattern-property.ejs
• templates/md/object-type.ejs
• templates/md/nested-property.ejs
• templates/md/join-type.ejs
• templates/md/innerSchema.ejs

The two lib files would be strait forward modifications. For the ejs files Wrapping the include() function to handle the search might be a good approach, imo.

[trieloff]

I feel like the templates are not stable enough to warrant good extension points. Are there specific overrides you have in mind?

[BrianWendt]

The big thing I wanted was the ability to do more with the README.md

I have my branch nearly finished for the enhancements I mentioned. Once I got in there and started hacking away I did end up also changing lib/schema.js.

I'm not a GitHub guru by any means so maybe you can help explain something; When I do npm install -g @adobe/jsonschema2md it pulls version 2.0.0 which is because npm has it as the newest version. However, master on GitHub is 1.1.1. Is 2.0.0 supposed to be the new version people are using?

[BrianWendt]

What about the stability is concerning?

[trieloff]

Thanks for the use case, that makes a lot of sense.

Maybe we should start with a method to set prefix and suffix for the generated README.md then. You'd simply pass in two files, and one gets prepended and the other appended to the generated README.md. We could also think of a solution for README.md in particular that mirrors the approach taken by https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/Create-a-README-template

What about the stability is concerning?

I would not consider any of the template files parts of a defined and reliable API, but rather an implementation detail. If we decide to change anything, i.e. #126 or #125 your customizations won't work anymore.

Is 2.0.0 supposed to be the new version people are using?

We are using semantic-release which is creating new version numbers automatically (but it's not yet updating the package.json), so the code you are seeing in master is 2.0.0, except that the version number in the package.json is not accurate.

[BrianWendt]

Thanks for the clarifications. I'll set up a script to generate the README.md for now.

[trieloff]

🎉 This issue has been resolved in version 4.0.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀