This is a very exciting release; a new model for representing the documents rendered by megadoc is introduced called the T.Corpus. This model enables us to analyze the database in a source-agnostic manner and provide many features out-of-the-box such as automatic indexing, URI generation, and more!
Probably the more exciting part is that we're now able to pre-render the documents to raw .html files, resulting in a greater level of accessibility and runtime performance.
.html, see Config.formatpluginNames list of the registered plugin names (inferred from the distributable JS files)title config itembin/devserver.sh has been modified to use connect with webpack-hot-middleware for local development. Also, /.local file support has been dropped; the server will now automatically resolve which plugins to use and use the local versions of themreadme config; use the markdown plugin with a rewrite for serving such a file(semver-major) megadoc no longer accepts a home config for redirecting
Markdown renderer now accepts a anchorableHeadings: Boolean option that
controls whether the <h{1..4} /> tags should have anchors. This affects
the renderMarkdown routines passed to the render phase plugins.
Spotlight is here! All the indexed documents have a chance to enter the Spotlight (engaged using Ctrl+K or CMD+K) and allow the user to quickly find the document they're looking for, or other related documents thanks to the fuzzy search algorithm it utilizes.
The Spotlight can operate in two useful modes:
@ as the first character of the query, or by using Ctrl+. or CMD+., in which the corpus is the set of entities for that document (what this means depends on the document type; for a markdown article, this would be the headings, for a JS module, this would be its functions/properties, etc.)The Spotlight also sports an intuitive keyboard navigation interface.
Currently supported plugins:
Anytime you're hovering over a link to an internal document, megadoc will now show a small tooltip that gives the reader a brief description of that document.
Very helpful for the times when you are not yet ready to leave the document you're currently reading, but have no idea what the referenced document is.
Currently supported plugins:
A new plugin for rendering static files at arbitrary URLs. Useful for rendering landing pages for other plugins, like js/markdown/API.
A plugin for rendering all the content in a single page. Useful for small projects orlibraries that consist of a bunch of files and a single API reference.
Navigation is done using a static/fixed sidebar to the left.
A plugin for rendering content in multiple pages. Primary navigation is achieved using a banner on the top, which supports arbitrary links and menus of links, and sub-navigation using a sidebar.
A new theme plugin that mimics Qt docs. Very nice looking for multi-page layouts.
This plugin will build an internal graph of all the inter-document links in the database. When viewing a document, a list of external documents that talk about the current one will be displayed. This helps the reader find related articles and explore the document database.
Currently supported plugins:
megadoc.use signature change
The new signature is:
megadoc.use(String, Function) -> voidAnd the function will be passed two arguments, the first is the plugin API,
and the second is the runtime configs registered for that plugin. This is for
convenience instead of having to reach out to megadoc.getRuntimeConfigs(...)
and is (currently) backwards compatible.
CJS::Landing for rendering custom landing contentconfig.navigationLabel and config.icon were dropped. Instead, use the layout for defining links.megadoc-plugin-reference-graph for generating a "Related Documents" list for modulesalias: Object<String,Array.<String>> that supports explicit aliasing of modules. Very useful when you do not control the source code for those modules, or do not want to change it.yard-api::Landing for rendering custom landing content<meta name="description"> is now modified to reflect the current article's summary. Very link when you're linking to megadoc documents in Slack or such that utilize the meta of the document when displaying those links.megadoc-run or megadoc run binary was restored to just megadocmegadoc compile is no longer a thing, use the megadoc-compile binary directly insteadPulled out the plugins that were previously in core into their own packages:
megadoc/plugins/cjs is now in megadoc-plugin-jsmegadoc/plugins/yard-api is now in megadoc-plugin-yard-apimegadoc/plugins/markdown is now in megadoc-plugin-markdownmegadoc/plugins/git is now in megadoc-plugin-gitThis patch was mainly concerned with file-size and run-time performance.
scrollIntoView implementationresizable implementationCollapsibleGroup was extracted from the CJS plugin and is now in core UIThis patch introduces a Single-Page layout in which all the documents are displayed in a single page. This is very useful for small projects that do not need the navigation functionality in the regular, multi-page layout.
One can toggle this layout by either specifying --layout="single-page" on
the command-line, or adding layout: "single-page" to the config file.
Only the CJS and Markdown plugins currently support the single-page layout.
Changes
inferModuleIdFromFileName from being respected(BREAKING) Internal changes
registerRoutes has been renamed to addRoutesregisterOutletElement was dropped; use Outlet.add directly insteadThis release brings a whole lot of improvements to the robustness of megadoc's parsers, the UI, and runtime performance since we now do all the content rendering at compile-time instead.
Also, plugins have been revisited and it's now very easy to write a custom plugin and hook it into the system.
run functionThanks to #3 above, the same plugin can now be used more than once with different configs.
The compilation now has two more phases:
index in which all the linkable entities may be indexedrender in which all plugins are expected to render their content to something the UI can display (mainly: markdown -> html and linkifying everything in that content)compilation object that was being passed to all stage processors has been dropped$inject and $defaults properties are no longer supported. A plugin's runner will receive the compiler as the only argument, and from there it can reach whatever dependencies it requires.emitter module is now the same as the compiler; just use compiler.on().megadoc binary now supports two commands: run for generating the docs, and compile for compiling external plugins--no-purge to run@lends support:@lends SomeObject.prototype@lends exports@lends SomeObject@throws@examplemotto: String for tuning the motto/slogan next to the titlemetaDescription: String for tuning the <meta description /> tagshowSourcePaths: Boolean for displaying the file path inside the module header--stats for generating compile-time stats@alias tagmegadocReact.use renamed to megadoc.useInternal changes:
/bin/test-ui.sh or karma start ui/karma.conf.jsnpm test (and npm publish) will now fail if there are any eslint, core-test, or ui-test failuresdiscardIdPrefixlaunchExternalLinksInNewTabs[/path/to/entity Custom Title]()allowLeadingSlashInLinkscjs plugin: module "static" methods (like exports.something = function()) are now linked to using the . symbol. For example: [exports.something]() instead of [exports#something]()cjs plugin now supports the @memberOf tag for documenting a module defined in a different file--plugin parameter for filtering active plugins at run-timegit plugin now accepts a transform() function that can post-process a
commit message's body for display in the Recent Activity sectiongit team leaderboard now displays the member count as well as the age of
the team (based on their first and last commit timestamps)--verbose and --debug flagsconfig.publicPath is set to an empty string "", the router will start serving from / and will no longer complain that no route matches /.Made with ♥ using megadoc.