3.3.10 (2022-05-09)
- fix ci (37a8765)
3.3.9 (2022-05-09)
- tech release (4e6e8c9)
3.3.8 (2022-05-09)
- tech release (5078ed5)
3.3.7 (2022-05-09)
- tech release (ac031f8)
3.3.6 (2022-05-09)
- tech release (a8fca45)
3.3.5 (2022-05-09)
- tech release (adb9614)
3.3.4 (2022-05-09)
All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
3.2.4 (2020-06-18)
- Updated all dependencies to latest
- Patched serve script
3.2.2 (2019-01-08)
- An issue where enumeration value would be incorrectly displayed as
undefined
in docs parsed from ES5 code. - An issue where
jsdoc.predicate
(orjsdoc.filter
) option would not be taken into account. - An issue where favicon would not be copied over to the output dir.
- (Zebra Template) An issue where some special characters within the location hash would cause an error.
Invalid assignment
error due to ES2015 syntax.
- Support for handling notation with multiple sub-types. e.g.
Map<String, Object>
. (PR #65 by @MaienM)
- Improved / cleaner symbol names and long names. This also fixes a JSDoc bug that unnecessarily and incorrectly wraps the last level of the notation in quotes and brackets.
- Updated dependencies to their latest versions.
3.1.0 (2018-12-04)
- An issue with
"path"
routing which led to 404 page, occurred when a (deep) route was refreshed or loaded directly. (Due to a bug in core dependency.) Fixes #62. - An issue where a (harmless)
TypeError
was thrown whendebug
is enabled. - An issue with
$docmaLink
due to missing trailing slash, when routing method is"path"
.
- (Zebra Template) Added JSDoc
@default
tag support for symbols. Fixes #60. - (Zebra Template) Added option
contentView.faLibs
that defines FontAwesome libraries to be included, such assolid
,regular
,brands
. Set tonull
to completely exclude FontAwesome from the output. See Zebra documentation. Fixes #63. - (Zebra Template) Added option
contentView.faVersion
that defines FontAwesome icon library version to be included.
- Improved SPA route handling.
- Updated dependencies to latest versions.
3.0.0 (2018-11-18)
- BREAKING: Dropped support for Node.js versions 6 & 7. Requires Node.js v8 and later. This change is due to updates to the core dependencies such as
fs-extra
,jsdoc-x
andjsdom
. - Improved path/query routing.
- BREAKING: Linking logic has some changes.
- (Zebra template) Improved support for constant symbols.
- Ability to force parser type on defined files/paths; by appending a suffix. For Markdown, append
:md
or:markdown
. For HTML, append:htm
orhtml
. For example,LICENSE:md
will force-parseLICENSE
file as markdown.file.partial:html
will force-parsefile.partial
as HTML. - Ability to create deeper paths for named groups/routes. e.g.
mylib/latest
- Support for favicon. Set
app.favicon
to your ICO file's local path. - Support for collapsable markdown (i.e. with
<details>
and<summary>
tags). This is great for generating styled collapsable lists (such as F.A.Q.) from your markdown files. If a bookmark (id) is passed in the location hash, that item will auto-expand. See Docma F.A.Q. for an example. Note that Edge does not support details/summary tags yet. All other modern browsers have support. - Ability to hide or remove specific, partial content from Docma output. For example if you want some part of your README to be visible in GitHub repo but not in your Docma generated documentation... See this for details.
- New CLI option (
-b
or--base
) fordocma serve
command to override/set the base path. - (Zebra Template) Added support for collapsable markdown (i.e. with
<details>
and<summary>
tags).
- An issue where documentation build would fail due to a symbol name being a non-string value. Fixes #54.
- An issue where the web app would throw
Uncaught TypeError
when invalid JSDoc type specified for@returns
. Fixes #55. - Fixed "Reverse Tabnabbing" vulnerability with generated documentation links. (This is also fixed for Zebra template.)
- An issue where
base
tag would not be added to the head of main document. - An issue where Docma would not set default
app.base
path to/
as expected. Fixes #59. - An issue where symbol link would be parsed as absolute path rather than relative. Fixes #50.
- (Zebra template) Fixed an issue where tags such as
@constant
and@module
would cause anUncaught TypeError
. Fixes #41 and #45.
2.1.0 (2018-04-29)
Thanks to @feugy for this PR.
serve
command now takesconf.app.base
parameter into consideration, and will redirecthttps://localhost:9000/
to it.
serve
command can handleconf.app.dest
relative path, and resolves them against current working directory.- A file name issue that produces
cannot find module
error in case-sensitive systems. Fixes #38.
- Renamed the
--quite
option to--quiet
. Alias-q
remains the same.
- Partial support for TypeScript-style type notation. e.g.
Promise<Number>
orNumber[]
, etc...
- An issue where deeper levels of tree nodes were not properly aligned, when
sidebar.outline
is set to"tree"
. - An issue where some symbol names were unnecessarily scroll-animated on hover. Firefox was affected.
- An issue where multiple return types were listed out of style.
- When
sidebar.itemsOverflow
is set to"crop"
(default); symbol names are faded-out on their edges, instead of using ellipsis (which behaves differently on browsers).
2.0.0 (2018-04-12)
This is a big release with some breaking changes.
Please read this changelog thoroughly before updating your Docma configuration.
- Support for documenting code with ES2015 syntax. (JSDoc and jsdoc-x dep. update.) Fixes #18 and #21.
assets
build configuration which provides ability to copy defined asset files/directories to build directory; so you can use/link to non-source, static asset files (such as images, PDFs, etc). See build configuration. Fixes #29.- Pre-build and post-build process support for Docma templates. See Docma Templates documentation.
markdown.xhtml
option for build configuration.- Docma version compatibility check for Docma templates.
clean
option that specifies whether to empty destination directory before the build. Default isfalse
.- Build statistics logs to console output. Now, displaying gzipped size of generated (docma-web) script, in addition to minified size; and more detailed summary of routes configured.
- An issue where the builder would not check for duplicate route names with the same route type (and silently overwrite the generated content file).
- An issue where compiled template scripts were altered when full-debug is enabled.
- An issue with redirecting a page when the routing method is set to
"path"
. - An issue with images in HTML (generated from markdown) that would overflow out of page. Now, limiting the image width to
100%
of parent container while keeping the aspect ratio. - An issue with generated heading ids when building docs from markdown. Other HTML tags contained within the heading were not ignored, resulting in too complex ids (bookmarks).
- BREAKING: Due to several upgrades (such as
jsdom
), Docma v2+ requires Node.js v6 or newer. - Greatly improved the symbol sorting logic (jsdoc-x). You can now sort by
scope
, byaccess
type, bykind
,grouped
oralphabetic
(default). Seejsdoc.sort
option in build configuration. - The destination directory is not auto-cleaned anymore before the build. Use
clean
option for the old behavior. Fixes #34. - Improved markdown parser. Both
<h1 />
and<h2 />
tags are now followed with a<hr/>
, like on GitHub. - Updated core dependencies to their latest versions.
- Migrated all code to ES2015.
- BREAKING: Docma templates are now node modules. Docma still comes with an updated, built-in default template (Zebra). But templates designed for Docma v1.x will not work with Docma v2.x.
- For template authors only:
- BREAKING:
docma.template.json
file that defines the template build and configuration options is dropped in favor of template module main (JS) file orpackage.json
. There are several other improvements. See updated documentation on Creating Docma Templates. - BREAKING:
compile
property of template configuration is removed. Now, scripts or less/sass files of the template should be pre-compiled. This is logical and speeds up the documentation build process of Docma.
- BREAKING:
- Option
--clean
to empty destination directory before the build. - Command
docma serve
for starting a static server for serving / testing the generated SPA. - Command
docma template init
for initializing a new Docma template project. - Command
docma template doctor
for diagnosing a Docma template. Useful for template authors.
- Dropped default configuration file name
docma.config.json
in favor ofdocma.json
(shorter) and.docma.json
if you need to hide it. This does not break anything, you can still use the former if you want. - CLI will now auto-check for a
docma.json
(or.docma.json
) file in the current working directory if-c
option is omitted. - Options
-v
(lowercase) and-V
(uppercase) are swapped.-v
gets the Docma version now (alias--version
). And-V
is--verbose
.
See CLI documentation for detailed information on updated CLI.
- Event
navigate
that's triggered either when route is changed or on hash-change. - Each symbol in
docma.apis[name].documentation
instances, now has a.$docmaLink
property. - New utility methods to
DocmaWeb.Utils
:.type()
,.getSymbolLink()
,.getLevels()
,.getParentName()
,.getParent()
,.isPackagePrivate()
,.isEvent()
,.isGenerator()
,.isCallback()
,.isConstant()
,.isInterface()
,.isExternal()
and.isMixin()
. - Utility methods
.getCodeTags()
,.getFormattedTypeList()
. Fixes #33. - Utility method
.trimNewLines()
. This also has a dust filter$tnl
.
- Broken bookmark links due to URI encoded characters after hash (
#
). e.g. when navigated to#MyClass%7EInnerObject
instead of#MyClass~InnerObject
. - An issue with
DocmaWeb.Utils.getLongName()
, occured after JSDoc core upgrade. currentRoute
parameter of theroute
event. Passingnull
instead of empty route object when route does not exist.- An issue with
DocmaWeb.Utils.isClass()
utility method wheremeta.code.type
is not set toClassDeclaration
. DocmaWeb.Utils.isProperty()
utility method. It'll now returnfalse
if symbol is a method/function. This also affects the following methods:.isStaticProperty()
,.isInstanceProperty()
.
- BREAKING: Docma utility methods are moved to
DocmaWeb.Utils
static namespace (formerly underdocma.utils
). DocmaWeb.Utils.getSymbolByName()
signature is changed.- Updated web-core dependencies.
- Docma templates are now node modules. This is the initial Template API. See updated documentation on Creating Docma Templates.
- Support for
@example <caption>Title</caption>
. Fixes issue #14. - Support for
@hideconstructor
tag. Fixes issue #21. - Support for
@event
,@emits
(and alias@fires
) tags. Fixes issue #35. - Support for
@generator
and@yields
tags. - Support for rest parameters (i.e.
...args
). - Support for
@since
tag. - Support for folding child members of parent symbols. Added template option
sidebar.itemsFolded
(boolean
) for setting the initial state. Fixes issue #26. - Template option
sidebar.toolbar
(boolean
) that toggles a tiny toolbar below the search box, for switching symbol list outline or quick-filtering symbols by symbol-kind. Enabled by default. - Template option
logo
(String|Object
) specifies the URL of your logo. If you need separate logos for dark and light backgrounds set this to an object. i.e.{ dark: String, light: String }
. Recommended size of a logo image is 120 x 120 pixels. - Template option
symbols.autoLink
(Boolean|String
) specifies whether documented types should be auto-linked tointernal
paths (i.e. Docma route if type/object definition is within the generated documentation) orexternal
URLs (MDN docs if it's a JS or Web-API built-in type/object such asString
); or both. Thanks to @warpdesign for the idea. - Template options
symbols.params
,symbols.props
andsymbols.enums
all taking a string value, either"list"
(default) or"table"
; defining the layout style for parameters, properties and enumerations. If you like the design in previous versions, set these to"table"
. - Template option
sidebar.animations
andnavbar.animations
(Boolean
) specifies whether CSS transitions and animations should be enabled for navbar, sidebar and listed symbols. - Template option
contentView.bookmarks
option (Boolean|String
) which automatically adds bookmark links to headings to content generated from markdown files. Default:false
. generator
badge for generator functions.
- Some spacing issues with class descriptions. Empty tables are auto-removed now.
- A JSDoc issue where the constructor would be incorrectly marked as alias.
- An anchor/bookmark issue with multiple symbols having the same id.
- Sub-symbols that are listed in a table, will not wrap to new line anymore.
- An issue where the (heading) title would be hidden under the nav-bar when navigated via a local bookmark on a page, generated from a markdown file. Also improved spacing for headings.
- An issue where the page would not scroll/jump to the bookmark on initial load; when the URL has a location hash.
- Pre/code elements not to wrap content. Now, horizontally scrollable (like on GitHub).
- An issue with sidebar symbol names auto-resizing incorrectly in some cases. Also improved performance by caching font-size for each item.
- hidden meta issue. If symbol had no class description, tags such as
@author
,@version
and@copyright
would not be shown. - Sidebar scrollbars that were not fully visible.
- Some issues with navbar margins when sidebar is disabled.
- Sidebar and navbar title so that they allow longer strings without breaking.
- Default template finally has a name :) - Zebra.
- BREAKING: You need Docma v2+ for latest Zebra template to work.
- Improved symbol listing styles and performance. Using CSS transitions instead of JS manipulation. Also; when search is active, outline is temporarily set to
"flat"
so that you see the parent of the symbol. When search box is cleaned, it's set back to the initial template setting. (e.g."tree"
if set). - Improved
@example
outputs. If there are multiple examples for a symbol, they will be numbered now. - Improved nested bullet list spacing, for better readability.
- Improved UI and responsive layout. On small screens, sidebar auto-collapses; top navbar turns into hamburger menu. Also, truly printable.
- Improved template option
.badges
(default:true
) to also accept a string value for custom bullets instead of badges. - Improved template option
.title
to also accept an object{ label:String, href:String }
so you can link it. - Various other improvements and clean up.
- The template options object structure is changed and a couple of options are renamed. Old structure is still supported and it won't break anything but this support will be removed in future versions. See documentation for the new & improved structure.
- BREAKING: icomoon selection of icons (and
ico-
CSS prefix) in favor of FontAwsome (v5) and SVG icons support. - Bootstrap and its dependencies (css and js). Also, cleaned up all unused styles.
1.5.3 (2017-12-21)
- A parser issue where carriage return (CR) of Windows newlines (CRLF) were removed. Fixes #28.
1.5.2 (2017-12-09)
$ is not a function
error on Windows. PR #23 by @warpdesign.- Some typos in documentation. PRs #13, #17.
Note: For this release, some dependencies (such as
jsdoc-x
,jsdom
) are NOT updated on purpose 'cause they introduce breaking changes. In v2 (WIP, to be released) these will be updated and many things will be improved.
1.5.1 (2017-03-11)
slice
error for non-string default value.
1.5.0 (2017-03-10)
config.jsdoc.ignored:Boolean
option which specifies whether to include documentation symbols marked with@ignore
tag.
- An issue where empty lines would be stripped out from
@example
content.
- Improved auto-indention for code in comments.
- Improved
$val
filter.
- Template option
outline
, which determines the outline style of the sidebar symbols list. ("flat"
or"tree"
). See documentation and this example foroutline
set to"tree"
. - Template option
symbolMeta
which specifies whether to add meta information at the end of each symbol documentation such as code file name and line number. Default isfalse
. static
badge for static members,deprecated
badge for deprecated symbols.
- Improved sidebar design.
Type.<T>
is now represented asType<T>
.- Default string values are now represented in quotes.
1.4.7 (2017-03-09)
- An issue where build config
config.jsdoc.includePattern
would not be respected when filtering files. - An issue where sorting would change when
config.jsdoc.hierarchy
option is enabled.
1.4.5 (2017-03-05)
- Build config options:
config.jsdoc.allowUnknownTags
,config.jsdoc.dictionaries
,config.jsdoc.includePattern
,config.jsdoc.excludePattern
(jsdoc-x
feature). - JSDoc plugin support via the new
config.jsdoc.plugins
option (jsdoc-x
feature).
1.4.0 (2017-02-13)
- Incorrect routing when routing method is set to
"path"
.
- If
config.app.entrance
is not set in build configuration, it now defaults to"api"
. - If
config.app.server
is not set in build configuration, it now defaults to"static"
. ("static"
is similar to"github"
which generates static HTML files.)
- Respecting debug option in config file. If no debug options are set in the command-line arguments (such as
--debug
,--quiet
,--nomin
,--jd-out
,--verbose
,--web-logs
); the bitwise debug value from the config file is used, if set.
.split()
error fornull
(404) routes.
- Updated web dependencies to latest versions.
- A style issue where sidebar would not scroll all the way to the bottom in Firefox. Fixes issue #8.
- If
config.template.title
is omitted,config.app.title
is used. (Defaults to"Documentation"
if not set).
1.3.0 (2016-11-23)
- Case-sensitive routing option.
config.app.routing
accepts either aString
("query"
or"path"
as before) or now, anObject
. e.g.{ type: "query", caseSensitive: true }
. This also fixes issue #3.
- Updated dependencies to their latest versions.
- Minor code revisions.
- Extended support for parsing back-ticks in documentation. Added triple back-tick support for multiline code blocks (
```
).
- Improved
docma.utils.normalizeTabs()
method. Deep indents in JSDoc comments/descriptions are also normalized. - Improved support for
<pre></pre>
tags within JSDoc descriptions.
- An issue where symbols with return type parameters (such as
Promise<Array>
) would not be escaped and parsed properly. Fixes issue #4. - An issue where boolean symbol parameters' default values would not be parsed properly. Fixes issue #5.
1.2.0 (2016-10-31)
- CLI (command-line interface). Supports
config
,src
,dest
and alldebug
options.
- Updated (one-dark) highlighting styles.
1.1.1 (2016-08-13)
- An anchor/linking issue which prevented some browsers (such as Safari) to navigate properly.
1.1.0 (2016-08-12)
- An issue where constructors would still show up in the documentation even though
@private
is set. Fixed byjsdoc-x
.
- Updated dependencies to their latest versions.
- Minor revisions.
- Fixed sidebar header/search position when sidebar is collapsed.
- An access badge is shown next to symbol name, if symbol has
private
orprotected
access.- Clean up.
1.0.3 (2016-06-27)
- HTML source file support. You can include HTML files together with JS and markdown files while building your documentation.
- Removed YAML syntax highlighting support because of incorrect auto-detection. Opened an issue here.
1.0.1 (2016-06-11)
David considers marked as insecure dependency. This is already reported.
- Missing web components.
1.0.0 (2016-06-11)
- Ability to convert markdown files to HTML. See documentation.
.markdown:Object
build configuration options. (Same asmarked
module options)..markdown.tasks:Boolean
option for parsing GitHub-like markdown tasks.- Emoji (twemoji) support for converted markdown files. Added
.markdown.emoji:Boolean
option. .app.server
build option that defines the server/host type for generating server config file(s) for the SPA. e.g., setting to"apache"
generates an.htaccess
file within the root of the generated output. Supports"apache"
and"github"
..app.base:String
build option that sets the base path for the SPA..app.entrance:String
build option that sets the initial content to be displayed..debug:Boolean
build option.- Ability to group
.js
files into multiple, separate documentation. See.src
build option. - Ability to rename routes for generated markdown files. See
.src
build option. - Negated glob support (that excludes the paths) for the
src
build option.
- Improved GFM parsing.
- Dropped
.dump
config option in favor of.debug
option. - Moved
.template.document
configuration to.app
.
- Client-side routing support for the SPA with paths (e.g.
/api/mylib
) or query-strings (e.g.?api=mylib
). Configured via.app.routing:String
option. Set to"path"
or"query"
. Uses page.js internally. - Implemented
EventEmitter
. - New methods to
docma.utils
such asgetCodeName(symbol)
,getFullName(symbol)
, etc...
- BREAKING: Dropped
docma.ready()
method. Usedocma.on('ready', listener)
that's only triggered once on every page load ordocma.on('render', listener)
triggered when each content is rendered. Also seedocma.on('route', listener)
triggered when SPA route is changed. - Docma web initializing errors are no longer passed to event listeners. They are now immediately thrown.
docma.app:Object
anddocma.template.main:String
are now exposed to the SPA.docma
object accessible by the SPA is nowObject.freeze
d.- If
debug >= 3
, web app will now also output logs.
- Bookmark scrolling.
- More supported languages for syntax highlighting (Javascript, JSON, CSS, HTML, XML, CoffeeScript, TypeScript, Bash, HTTP, Markdown, Dust and YAML).
- Ability to auto-detect language for syntax highlighting.
- Ability to style tables in HTML generated from markdown.
- Ability to style code blocks in HTML generated from markdown.
- Documentation of
@property
JSDoc tags. - Incorrect symbols sort issue when symbol(s) have aliases.
- Updated default template structure.
- Improved layout for HTML files converted from markdown.
- Improved font display for code and summary/descriptions.
- Improved UX by auto-adjusting font size of sidebar items to fit the sidebar, if they exceed the width.
- Improved various API documentation styles.
- (Dev): Manage web-component dependency packages via Bower.
- Updated project structure.
- Various minor revisions and clean-up.
- Improved Docma source code documentation.
- Default template option
badges:Boolean
.
docma.template.json
is no more copied over to the output.
- Docma Web file paths.
- Updated default template.
- Updated dependencies.
- Clean-up.
- Initial (pre) release.