Not able to use a custom theme / docs unclear on how to do it.

[tmcconechy]

How exactly does one make a custom theme work: I tried initially to

• copy this folder locally in my project to docs/theme https://github.com/documentationjs/documentation/tree/master/src/default_theme
• run command
  documentation build --format html --theme docs/_theme --output docs/api/

I get an error:
/Users/tmcconechy/Dev/4.3.1/docs/_theme/index.js:22 comments: Array<Comment>, ^ SyntaxError: Unexpected token : at Object.exports.runInThisContext (vm.js:78:16)

Tried beta 14 and now 18 to be sure. How does one succeed in getting it work with a theme?

Specifically i want to modify the markdown my usually command is:

documentation build myfile.js -f md --theme docs/_theme -o myfile.md

Theme is ignored in this scenario as well.

Was hoping if i point it at a theme it would use that before generating the MD as per https://github.com/documentationjs/documentation/blob/master/docs/THEMING.md

[tmcw]

Hello!

Re: main question about modifying themes:

• The files in src/ are source files: they're written in ES6 with Flow annotations, so they won't run uncompiled. They're compiled to ES5 sources in /lib/ when this module is built (using Babel).
• So, you can get a runnable version of the theme by cloning, installing, and running npm run build (or yarn build if you're using yarn)

---

That said, this is all relative to HTML themes, not Markdown. As it stands, you could do a ground-up theme that generates Markdown, but that isn't the main intent of the theming code - themes are intended to be for HTML, which has more opinionated style decisions, rather than Markdown, for which we try to make the defaults great (and also Markdown is generated from an AST, not through templating like in most themes).

Is there anything in the Markdown theme that you specifically want to get improvements over?

[mhkeller]

I ran into this also. It would be great there were a separate repo with the default theme already built. You could point to it in the docs and say "To create a custom theme, download this and modify it."

[mhkeller]

@tmcconechy fyi, I also had to replace require('../') with require('documentation') inside of default_theme/index.js once it was in my project.

[zeke]

cc @gr2m who is trying out documentationjs for GitHub's new JS Octokit.

[jmbothe]

I am having a similar issue, although I have followed the instructions in this issue up to this point:

• I cloned, installed, and built the repo.
• Copied /lib/default_theme to my project at /docs/theme.
• Replaced require('../') with require('documentation') in theme/index.js.
• Then I ran documentation build index.js -f html -t docs/theme -o docs/api/.

It creates documentation without error, but it doesn't look like the theme here. Instead, it looks exactly the way it would look if I were to omit -t docs/theme from the command.

On a related note, can anyone tell me why it lists the name of the function twice? thanks!

[tmcconechy]

My command is
documentation build <js file> --format html --theme docs/theme --o <output folder> --shallow
Maybe you need -- double dashes or spell out --theme.

Without seeing the file you documented, i think one is the file name and one is the constructor signiture. But you should be able to modify that by changing the index._ and index.js to your needs.
My index.js ended up being pretty heavily modified once i figured it all out.

[jmbothe]

Unfortunately adding double dashes and spelling everything out had no effect :(

[jmbothe]

Ok. Feeling a little dumb. So, the command is working. The problem is that the link in the README says that the example is built with the default template, but looking at the source code it doesn't seem to be the case. Can anyone point me to the theme that is used in the html example in the README? thanks!

OR explain to me how to nest namespaces in the sidebar default theme...

UPDATE: I figured out how to nest namespaces, but would still like to get my hands on that theme :)

[madorb]

Amen to what @jmbothe said. The themes are incredibly confusing. There doesn't seem to be a good list of available themes and the example http://documentation.js.org/html-example/ is clearly not generated using the default theme. @tmcw could you possibly let us know / document the theme used in that example?

Even better would be to describe the command used to generate that particular example

[tmcw]

The html-example is just the default theme from several documentation.js versions ago, which was replaced by the current theme, and it was generated by the normal build command. The APIs have changed so that old default is no longer up-to-date or compatible with the current codebase.

Sorry about this, but referring to my reply on the other thread - my computer time is heavily invested in building a startup and I need to spend more time with my bonsai and other hobbies. Please, if you/your company relies on this thing, pay it forward by helping out / digging for answers in the code / submitting PRs, because open source is/can be a team sport.

[tmcconechy]

I dont have time just right now for a PR either but if this helps the way that helped me was to figure out that if you look into index.js in the theme. Consider that "root" of the theme. You can remove and add in JS and stuff to change the data and spit it out in whatever format you like.

This happens to use underscore templates. But in that code its actually rendering the templates in the in this js. So essentially you can totally do what you want in this file, make it spit out html any way you like.

I saw these examples as well (some older / different API versions) but you can see in the mapbox one they wanted react components instead so changed index.js around.

https://github.com/documentationjs/documentation/tree/master/src/default_theme
https://github.com/mapbox/mapbox-gl-js/blob/master/docs/pages/api.js

[JustinGOSSES]

Posting in case a version of myself stumbles upon this issue like I did....

I just wanted to change some very small aspects of the styling for how the HTML pages were rendered. The default instructions for doing that seemed complicated. This is also reflected in the multiple issues on this. I appreciate it is hard, or maybe even impossible, to create a way to do styling that is both easy to understand and covers all the needs of this problem space.

For my simple changes to an html page, I found what worked for me was just putting a <head><style></style></head> tag inside one of the "description" blocks in the documentation.yml file.

My code looks like this:

- name: wellio
    description: |
      <head>
        <style>
        h2{
          color:black;
        }
          code.black{
            background-color: #295377;
            
            overflow: hidden;
            padding: 0.5rem;
            color: white;
            font: 0.8rem Inconsolata, monospace;

        
            width:100%;          
          }
        </style>
      </head>

      ### Wellio.js is a JavaScript library for converting a LAS 2.0 well log file into a wellio style JSON.

      #### Reason for Existing:
      Why would you want to do this? You can think of both LAS 2.0 and JSON as file formats that hold strings. 
      The difference is <a href="https://en.wikipedia.org/wiki/JSON">JSON</a> is a very common data format widely used across a variety of computer languages. It is used extensively on the web to hold data. 
      LAS 2.0 is not. LAS 2.0 is specifically for well logs. <a href="https://en.wikipedia.org/wiki/Well_logging">Well logs</a> are measurements along a well bore that meausure changes in subsurface properties.
      By converting LAS 2.0 to JSON, we get data into a format that is much easier to work with on the web. 
      Wellio's companion library  <a href="https://github.com/JustinGOSSES/wellioviz">wellioviz</a> takes the JSON that results from Wellio and visualizes it by leveraging <a href="https://d3js.org/">D3.js</a> v5. 
      However, you could visualize the same wellio JSON with a wide variety of other visualization tools too, because nearly all of them can consume JSON.

To my surprise, this let me change any of the default styling I tried to change.

Easy
Just works.

I suspect there's things it doesn't work out well for...and it certainly won't work for markdown styling, but it worked for my small changes to a single html page and was way easier than the default instructions for how to change the theme.