search

jleyba / js-dossier

A JavaScript documentation generation tool.
Apache License 2.0
149 stars 15 forks source link

customPages option should reference HTML not markdown #103

Open myphysicslab opened 7 years ago

myphysicslab commented 7 years ago

Currently the customPages option needs "the path to the markdown file to use". There are two problems with this:

  1. I'm using multimarkdown and so my pages will not render correctly with whatever markdown processor Dossier is using.

  2. Links to other files are made a bit more complicated because the result (the html generated from markdown) is put in the /page subdirectory, which affects "relative" links.

If we can specify the location of an HTML file in customPages, then both of these problems go away.

jleyba commented 7 years ago

With respect to markdown processing, Dossier uses atlassian/commonmark-java, which is based on CommonMark

myphysicslab commented 7 years ago

I might be able to adapt to using CommonMark instead of multimarkdown, but here are the things that would make that difficult.

  1. I frequently use the multimarkdown feature that generates links to headings. (MMD also autogenerates those references within the document which is very convenient.) I notice that atlassian commonmark-java has an extension for generating heading anchors -- that would solve at least part of my issue here. Otherwise I could hand code anchors by adding something like <a name="headingname"></a> before each heading.

  2. I use the multimarkdown feature that lets you specify the CSS file to use, as well as the Title of the web page. These are metadata items, and I don't think there is any way to do this in regular markdown. Here is an example:

CSS: ./Overview_2.css
Title: Architecture of myPhysicsLab
  1. Having the generated pages being in the pages/ subdirectory is something I could adapt to, but it means making links more complicated without any benefit. For example here are changes I would have to make in many places in markdown files: 
    [Clock](myphysicslab.lab.util.Clock.html)  becomes
[Clock](../myphysicslab.lab.util.Clock.html)

    Here is how references in JavaScript files to a markdown file would change:

    [Internationalization](Building.html#internationalizationi18n)  becomes
[Internationalization](pages/Building.html#internationalizationi18n)