Render markdown without TOC option

[windgazer]

Since I'm trying to generate wiki pages out of my jsdocs and the wiki takes care of TOC's, on top of that my wiki doesn't actually allow HTML-tags, it'd be nice if you could allow for an option that skips any TOC generation (including skipping the HTML-anchors for id purposes).

[75lb]

well, it’s currently possible to do those things.. but requires some knowledge of dmd and the templates.. i’ll think about how i can make it easier..

are you using the current release, or @next preview release?

[windgazer]

I'm using current, but I've been browsing both parts of the repo to try and get a handle on things. By now I've managed to get a rudimentary version of what I wanted by passing along empty anchor.hbs and index.hbs partials. Also, as this is certainly has an impact on my use, I'm primarily using the grunt plugin. Perhaps a usage example that explains how a partial can easily be overwritten and what the impact can be might help others to get to the end-solution much faster :)

[75lb]

looking into this.. incidentally, which wiki software do you use?

[75lb]

html tags are required for certain features.. for example, the docs sometimes have types which link to other parts of the docs, e.g.:

human.liver → Organ

this is rendered with this markdown:

human.liver →  <code>[Organ](#Organ)</code>

if you replace the <code> tags with the markdown syntax for code blocks (the backtick), you lose the hyperlink:

human.liver → [Organ](#Organ)

which is rendered by

human.liver →  `[Organ](#Organ)`

so would you be ok with losing a few features like this?

[75lb]

on @next i have added none options to --module-index-format and --global-index-format.. so you can now skip the main index by passing something like:

$ jsdoc2md -m none -g none yourcode.js

reinstall to try it out:

$ npm install -g jsdoc-to-markdown@next

[windgazer]

Damn, this is way more involved than I had thought! The wiki software in question is Bitbucket, which uses a 'safe' setting that doesn't allow any html (above and beyond stupid as they even refuse to acknowledge entities). The biggest sore was certainly with the created index and the anchor-tags that it required to be able to have id's to target. It resulted in an index with links that didn't work and plain-text printed anchor-tags that were fouling up the content. Since the wiki-format is extremely bare-bones, rather less feature and clear readable content at this point! I'll have a test-run with @next in the morning before I get back to my project. Thanks for picking this up so quickly, or even picking it up at all!

[75lb]

ok.. i'll have a look at a Bitbucket wiki tomorrow.. awkward bastards.. we should get it working..

[windgazer]

Alright, if you're going to dive into that, some things of note:

• Bitbucket wiki pages can generate an index for the current page using [TOC]

• All headers in Bitbucket wiki get an id set to markdown-header- plus the lowercase header content with all non-word characters replaced by a dash. For instance

  <h1>My Header</h1>

  would get the id

  <h1 id="markdown-header-my-header">My Header</h1>

• My current quick and dirty hack: https://gist.github.com/windgazer/d44f486d832afb1cb338

[windgazer]

I had a look at the output and it's definitely where I wanted this request to go. However, as I've also been digging through customising the .hbs partials I'm starting to wonder if this increased complexity of your templates is worth it. Alternately, would it not be more interesting to invest a little time in documenting/explaining how to quickly make a new plugin? That way users have far superior flexibility of features without you needing to be involved in every new feature people might think of. Consequently if a plugin turns out popular, it could still be streamlined into the main project!

[75lb]

just fyi, i haven't forgotten about this.. in fact i'm going to work on it next.. it'll be a dmd plugin, as you mentioned.. at the moment, jsdoc2md output looks shit on Bitbucket, and i need to change that before release..

[windgazer]

Nice!! I've been using my 'acceptable for now' hack for now and got back to the actual coding my project part :) I was meanwhile hoping that some more detailed description of how to make a plugin would show up on your project, it just wasn't clear enough within the time-box I had for getting it to work...

Looking forward to what you'll come up with and honestly, if you need a hand at any point, I can do a lot with some helpful pointers! Throw any test-build at me if your need a second pair of eyes and such. Or beyond that, if you scaffold a plugin I'm happy to tinker with the contents to make it look good on github.

[75lb]

morning! i did write some docs for the plugin method, if you look at the dmd next branch.. feel free to attempt the plugin - it's definitely required.. it's all a bit "alpha" though at the moment so just shout if you get any issues..

[windgazer]

I'm going to pin this on my board for monday. Knowing where to look for information is half the battle after all. I'll go have a stab at it and see if I can get a plugin to run. Will poke you should I get lost in the woods somewhere along the way :)

[75lb]

hi.. i made a start on a plugin for Bitbucket.. any thoughts?

https://github.com/jsdoc2md/dmd-bitbucket

[windgazer]

Damn that looks good. I don't quite understand how you made that happen with so little code! I used it on my main project (the one for which I at least cleaned up my jsdoc enough to works properly) with a custom template to trigger the TOC on Bitbucket and it's miles beyond what I had before.

The docs are way more readable and because of the nice use of sub-headings the TOC is nicely layered too now...

[windgazer]

I think I would personally group the Kind line with the heading of a section. For instance:

### "TriggeredPromise"
**Kind**: event emitted by generator  

A promise that fires events for allowing an external class to have a final say
in the success or failure of a Promise.... blahblahblah

This because a person who doesn't know the code should be able to immediately spot what kind of subject this doc is about.

Also one of the things I was thinking about is creating a helper to re-create the links used in your github version. Any header in Bitbucket has a predictable id, so making links to them should be feasible. The storm that swallowed up my last two weeks is passed so I should be able to tinker with this next week.

[75lb]

yeah.. it makes sense to move the Kind field up doesn't it..

it would be very useful to override the link helper for Bitbucket.. let me know if you have any problems with that.. tbh, i feel dmd is too hard atm.. too complex and not intuitive to edit.. even i found the process of making a plugin a lot of effort.. i will put some effort into making it more simple this weekend..

[windgazer]

Well, I'll be honest, it certainly is not intuitive. But it is easy to see how powerful it is. My biggest challenge remains finding out which bit are where and where to put my own bits to over-ride them. Luckily I've also been poking around at Mustache a lot for my blog lately so that helps me understand a few things a lot better :)

[75lb]

hehe, i know.. and it was even less intuitive a few months ago.. i'm working on it - we'll get there eventually.

"My biggest challenge remains finding out which bits are where and where to put my own bits to over-ride them" - this summarises perfectly what i need to fix.. the experience should be "it is obvious which partial generates what and simple to override it."

[windgazer]

Alright, I may not always have time to help you code parts of this effort, but I'll promise to always take time to review anything you need an extra pair of eyes on :) Least I can do, cause I intend to make this toolset part of my default grunt setup...

[75lb]

cool, thanks.. a few months ago i started building a dmd sandpit webapp - you paste in some documented source code and hack around with the dmd templates to see (in realtime) how it affects the output.. will publish that soon, will make life easier..

[windgazer]

Well, I've smashed my head into the wall a few times today :) How on earth did you do development on your plugin? I've tried using the cloned repo as a 'local' dependency in NPM, but as it turns out, it was happily ignoring any changes I made :( NVM, I cheated and soft-linked the directories

[windgazer]

Where on earth does >sig-name come from? I can't for the live of me figure out how to pass it, whatever that is, into my helper :(

[75lb]

Hi! sig-name is a partial.. it renders markdown using data from the sig helper in ddata..

you can’t pass a partial into a helper..

[75lb]

regarding your previous question, get to know npm link

[windgazer]

Dinner was good for getting my head on straight :) In my head I was running of to some far-flung idea that in reality was hardly necessary. So, back to just re-writing sig-link.hbs I'll keep muddling around with my current cheat, but I'll check up on npm link later!

[75lb]

ok.. sorry it’s such a bitch to modify, but i’ll fix that.. also, check out https://github.com/borisirota/jsdoc2md-anchors

[windgazer]

Hmm, there's a lot here I'm unfamiliar with and I'm sometimes awfully slow in picking that up. The more I dive into it, the more sense it's starting to make... Actually, once I got my dev environment to pick up the changes I made, then found out where I needed to tweak things, it all went fast enough :)

I personally don't like adding another tool at the end of the chain, especially since the whole idea of your dmd is to be able to modify templates for specific uses... I got bitbucket link rendering to work on my fork! Next up is to get the links for @see and perhaps @emits to work too. But first I'd prefer to hear if what I've done makes sense to you. (https://github.com/Windgazer-Freelance/dmd-bitbucket/commit/de118c0cdd1adc951878c2b902c3501be2497e7b)

[75lb]

i installed your plugin on one of my projects:

$ npm i git+https://github.com/Windgazer-Freelance/dmd-bitbucket.git

and ran it like so:

$ jsdoc2md --plugin dmd-bitbucket --src lib/*.js > README.md

looks good! Seems to work.. there are still a few minor imperfections (not only regarding links) but we're making progress.. feel free to commit a PR when you're ready..

[75lb]

what's the status here, do we still have an issue?

[windgazer]

You're quite right, this issue is certainly resolved!