Can't document `typography.less`

[tomgreever]

When I try to generate documentation from a file named typography.less DocumentJS seems to ignore it. I assume it might be because the theme files also use a typography.less file, but not sure.

At the top of typography.less I have:

/**
* @stylesheet typography.less Typography
* @parent styles-theme 1
*
* @description
* Typography should be used as a baseline to indicate hierarchy on every page of the application.
* Always choose the appropriate text size for the specific part being laid out, to communicate
* importance among headlines, content, microcopy and controls.
*
**/

When I generate the docs, Typography is not listed in the menu:

If I change the @stylesheet declaration to anything else, like this:

/**
* @stylesheet typography Typography
...

Then the generated docs add Typography to the nav:

What's strange is that I have another project where typography.less is used as the name and, as far as I know, it works. So perhaps this is only isolated to my project, but I'd like to know if it can be reproduced.

[justinbmeyer]

There can only be one typography.less. Do the themes also have a @stylesheet directive?

In general, it's best to name everything like a module. If your project is called "my-project", everything should look like:

@stylesheet my-project/typography.less Typography

[tomgreever]

Ok, yes - the issue is that the default DocumentJS theme has documentation in it and it also has a typography.less : https://github.com/bitovi/documentjs/blob/master/site/default/static/styles/typography.less#L2

/**
* @stylesheet typography.less Typography
* @parent Styles.baseline-elements 1
...

Solutions for me:

• Rename all the theme .less files to be prefixed with theme- and update the comments
• Add the theme folder to ignore in documentjs.json

@justinbmeyer if the recommendation for users is to reference their files like my-project/typography.less then we should update the documentjs theme docs to use this same convention. That will avoid conflicts like this in the future and demonstrate this best practice.

I'd also recommend that DocumentJS throw a warning when there are two references to the same named page. As a user, I have no idea why it didn't work. The console gives no warning and viewing it in the browser only removes it from view.

I can open issues for these two:

1. Update theme docs to follow the recommended naming convention
2. Show a warning when DocumentJS finds duplicate references