Custom readme templates

[AriTheElk]

Are there any plans to add support for custom readme templates? When generating multi docs, there seems to be zero control over the format of the markdown files that are output.

I think it would be really useful as then you could brand the docs a little better.

[jdx]

we're pretty happy with the layouts ourselves so we likely won't be spending any time on it, but I do think it's a good idea and would welcome suggestions and PRs on how it could be altered

[jdx]

maybe we could do something with _.template() to allow you to override it completely somehow

[AriTheElk]

Alright, that was going to be my next question :smile_cat: I'm in the process of building out a pretty complex cli app and would personally love to be able to have branded doc pages, even if it's just so I can add more emoji

Maybe I'll throw up a PR sometime this week to get your thoughts on it. Since oclif core is using ejs, maybe it would make sense to use a similar implementation here? That way even if we don't allow custom templates, at the very least it would preserve changes made to any of the command docs

Just an idea

[jdx]

We already use _.template() inside the CLI so I think that makes sense. However the syntax for that is very similar (possibly even identical) to ejs.

I'm not sure if this code is totally legible, but we do this for the s3 keys if you want to override them: https://github.com/oclif/config/blob/master/src/config.ts#L376

Where they are set something like this in the package.json:

oclif: {
  s3: {
    templates: {
      unversioned: "<%- channel === 'stable' ? '' : 'channels/' + channel + '/' %><%- bin %>-<%- platform %>-<%- arch %><%- ext %>"
    }
  }
}

I think we could do the same here. Add a property like oclif.readme.templates.command that we could pick look for in dev-cli to build a templatized readme command.

[jdx]

I realize that having a massive string multiline string inside the package.json is annoying to say the least, but rather than use a new config file I think it would make more sense for us to allow setting the all the oclif properties in a yaml file. (which could just go into the config loading stuff)

[jdx]

I think for commands at least you'd just need to replace this bit with a lodash template: https://github.com/oclif/dev-cli/blob/master/src/commands/readme.ts#L149-L153

Turns out I'm actually using _.template() in this file a lot already.

[AriTheElk]

Yeah, I think using a yaml file would be the saner option of the two. Something like .oclif.yml at the root of the project, a la .travis.yml? Are yaml's multiline strings capable of containing markup without having to escape?

[jdx]

yes but that's a more involved change that would have to happen inside of @oclif/config since I wouldn't want to simply add a new config file. Developers should either have a yaml config or package.json config but not both.

[jdx]

if you just assume package.json for now (which you can easily access with config.pjson.oclif, later I/we can look into making that change

[AriTheElk]

Oh for sure. I'll try out using a template from the package.json config. Was adding a yaml config something that was already on your roadmap?

[jdx]

yes and no, I've considered it for a while but this is definitely the most compelling reason to support it

[jdx]

If you want to look into doing that as well you can, roughly I think what we would do is check if there is a yaml file and if so, read it after this line: https://github.com/oclif/config/blob/master/src/plugin.ts#L101

and replace this.pjson.oclif with the contents of the yaml file.

Ideally we should support json and js as well. I think there is actually an issue somewhere where someone wanted to be able to configure via js.

[Aghassi]

Any movement on this? I'd like to modify this on our CLI so that we don't have the NPM install line and instead have it show a brew install https://github.com/oclif/dev-cli/blob/master/src/commands/readme.ts#L81

[jorge0136]

I too am finding myself wanting to inject custom readme content. Is moving towards a .oclif.yml still in the works? If one wanted to start moving this forward would that be the right direction to head?