drarig29 / typedoc-plugin-extras Goto Github PK

View Code? Open in Web Editor NEW

14.0 3.0 3.0 264 KB

A plugin for TypeDoc which adds extras to the generated documentation

Home Page: https://drarig29.github.io/typedoc-plugin-extras/

License: MIT License

TypeScript 100.00%

hacktoberfest typedoc-plugin typedoc

typedoc-plugin-extras's Introduction

typedoc-plugin-extras

This plugin only works for HTML documentation.

A TypeDoc plugin to add extras to the output documentation.

It allows you to:

Set a custom favicon.
Add the date/time of generation after "Generated using TypeDoc" in the footer. (cf. the example below)
Set a custom top-most title name (without changing the package name, like --name would do).
- For example, you could have --customTitle "Go back" --titleLink <url-of-your-parent-documentation>
And more... (cf. the list of arguments below)

No date/time will be added if --hideGenerator is set (because the footer wouldn't exist).

All extras are disabled by default: they are opt-in.

Feel free to ask for another extra or to make a PR 😉

Example

You also can view an example documentation using the plugin here:

https://drarig29.github.io/typedoc-plugin-extras/

Installation

npm install --save-dev typedoc-plugin-extras

Usage

$ npx typedoc --plugin typedoc-plugin-extras [args]

Arguments

The following arguments can be used in addition to the default TypeDoc arguments.

--customTitle
Specify a custom title, for the top-most title only.
Example: foo
--customDescription
Specify a custom <meta name="description" property.
Example: An example description
--favicon
Specify the path or URL of the favicon file.
Example: public/favicon.ico
Note: If given a path, the favicon file is copied into the documentation's output directory (--out).
--footerTypedocVersion
Appends the TypeDoc version in the footer.
Default: false
--footerLastModified
Appends a "Last Modified" text in the footer (e.g. "Last modified 6 min. ago").
Default: false
Note: If specified, the --footerDate and --footerTime options are ignored.
--footerDate (deprecated)
Appends the date of generation in the footer (e.g. "Jul 29, 2022").
Default: false
Note: If combined with --footerTime, it will append "Jul 29, 2022, 3:44:42 PM GMT+2".
--footerTime (deprecated)
Appends the time of generation in the footer (e.g. "3:44:42 PM GMT+2").
Default: false
Note: If combined with --footerDate, it will append "Jul 29, 2022, 3:44:42 PM GMT+2".

Testing

To test this plugin, you can generate TypeDoc documentation for this plugin.

To do so, you'll first need to build it:

npm run build

Then, you can generate the documentation with the plugin (from source):

npm test

License

MIT

typedoc-plugin-extras's People

Stargazers

Watchers

Forkers

arlopezg joukevandermaas mrrefactoring

typedoc-plugin-extras's Issues

Say more in the description

Mention favicon, title or else in the package.json description.

Deprecate `--customTitleLink` and `--gaMeasurementId`

Issue created from #19.

customTitle -> name

This plugin's custom title option works a bit differently: it doesn't change the project name (like --name), but only the name of the link in the header of all generated pages. This may need a note in the README, or a better explanation.

Example with --customTitle "Go back" (taken from here)

customTitleLink -> titleLink

The titleLink option was added (in [email protected]). Let's deprecate customTitleLink in the next release.

gaMeasurementId -> gaID

I made a mistake blindly resolving a feature request (#17), without checking if it was supported or not...

It is indeed already supported, and produces quite the same output.

The script is just put in different places in both implementations (see the HTML below). This plugin puts the script in the head (recommended), while typedoc puts it at the very end of the page.

Let's open an issue on TypeDoc saying that this is not recommended, and let's deprecate this plugin's gaMeasurementId option too.

<!DOCTYPE html><html class="default" lang="en"><head>
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=withGaMeasurementId"></script>
<script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());

    gtag('config', 'def');
</script>
<meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Documentation</title><meta name="description" content="Documentation for Documentation"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/search.js" id="tsd-search-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os"</script><header class="tsd-page-toolbar">
<div class="tsd-toolbar-contents container">
<div class="table-cell" id="tsd-search" data-base=".">
<div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M15.7824 13.833L12.6666 10.7177C12.5259 10.5771 12.3353 10.499 12.1353 10.499H11.6259C12.4884 9.39596 13.001 8.00859 13.001 6.49937C13.001 2.90909 10.0914 0 6.50048 0C2.90959 0 0 2.90909 0 6.49937C0 10.0896 2.90959 12.9987 6.50048 12.9987C8.00996 12.9987 9.39756 12.4863 10.5008 11.6239V12.1332C10.5008 12.3332 10.5789 12.5238 10.7195 12.6644L13.8354 15.7797C14.1292 16.0734 14.6042 16.0734 14.8948 15.7797L15.7793 14.8954C16.0731 14.6017 16.0731 14.1267 15.7824 13.833ZM6.50048 10.499C4.29094 10.499 2.50018 8.71165 2.50018 6.49937C2.50018 4.29021 4.28781 2.49976 6.50048 2.49976C8.71001 2.49976 10.5008 4.28708 10.5008 6.49937C10.5008 8.70852 8.71314 10.499 6.50048 10.499Z" fill="var(--color-text)"></path></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div>
<div class="field">
<div id="tsd-toolbar-links"></div></div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li></ul><a href="https://google.com" class="title">Custom</a></div>
<div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><rect x="1" y="3" width="14" height="2" fill="var(--color-text)"></rect><rect x="1" y="7" width="14" height="2" fill="var(--color-text)"></rect><rect x="1" y="11" width="14" height="2" fill="var(--color-text)"></rect></svg></a></div></div></header>
<div class="container container-main">
<div class="col-content">
<div class="tsd-page-title">
<h2>Documentation</h2></div>

...

<div class="overlay"></div><script async src="https://www.googletagmanager.com/gtag/js?id=withGaID"></script><script>window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'abc');</script></body></html>

Improve documentation for --customTitle
Deprecate --customTitleLink
Create an issue and deprecate --gaMeasurementId

Use idiomatic English for footer date/time

The footerDate option currently displays something like:

Generated using TypeDoc version 0.22.15, the 5/1/2022 at 2:53:15 PM

This reads incorrectly in at least American English and I would suggest it should be:

Generated using TypeDoc version 0.22.15, on 5/1/2022 at 2:53:15 PM

https://github.com/Drarig29/typedoc-plugin-extras/blob/master/src/main.ts#L111

I would also suggest showing the time zone since you are displaying a locale specific time and not UTC otherwise it would not be possible to know in which time .

Or, even better, just remove the English prefix words and just display a locale friendly version of the full date and timestamp that is usable anywhere.

Generation fails when using the built-in `minimal` theme

The plugin fails to append the generation timestamp to the footer when using the built-in 'minimal' theme. When using the default theme, the plugin works as expected.

Error: Cannot read property 'innerHTML' of null

How to reproduce:

npx typedoc --plugin typedoc-plugin-extras --theme minimal

Analysis:

The error occurs because the plugin uses the direct descendant selector to locate the generator container div.

if (!this.application.options.getValue('hideGenerator') && (!hideDate || !hideTime)) {
  p = document.querySelector('body > div.container.tsd-generator > p');
  ...

However, when using the minimal theme, Typedoc adds some additional container elements between the body and the generator div.

DOM structure when using the default theme:
body > div.container.tsd-generator > p

DOM structure when using the minimal theme:
body > div.container.container-main > div.content-wrap > div.container.tsd-generator > p

Removing the child combinator between body and div.container.tsd-generator solves the problem.

Workaround:

As a workaround, if someone else also encounters this problem, simply disable the generation of the generator info by setting the flag --hideGenerator.

Version:

typedoc: v0.17.7
typedoc-plugin-extras: v1.1.3

add og:Image

I would be nice if you can add the posibility to set the og:Image tag. As a particularly click-attractive part of the Open Graph tags, og:image is very important. Choose an appealing image that encourages users to click or share. In order to be able to control the display in the stream of the target group as completely as possible, a specially created og:image is recommended, especially for socially relevant content. The article image, which is also used on the website itself, usually still has good optimization options. If you do not define the og:image tag on Facebook, for example, users can select an image themselves in the social preview. Since advertising banners, icons or other elements of the page are often also available for selection in this preview, defining the Open Graph image should be mandatory for you.

Not working with Typedoc 0.24.8

Option Errors

The plugin options are currently not working and Typedoc emits errors such as:

[error] Tried to set an option (favicon) that was not declared. You may have meant:
        version
        json
        navigation
        options
        out
        cname
        gaID
        watch
[error] Tried to set an option (footerTypedocVersion) that was not declared. You may have meant:
        version

Officially Supported Options

Options have been added to Typedoc:

customTitle -> name
customTitleLink -> titleLink
gaMeasurementId -> gaID

Add Google Analytics / Tags extra

It would be cool if you made an option to add an analytics code!

You could then create a script element and insert it into the DOM as the first child of the head element.

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=THE_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'THE_MEASUREMENT_ID');
</script>

URL for favicon

Hi @Drarig29! Thanks for your plugin.

I considered adding a favicon to my docs via URL to host where SVG placed.

What do you think about this functionality?

Add a footerLastModified option

Maybe a --footerLastModified option would be a nice feature to add.

This could be better than the current --footerDate and --footerTime options...

Something like Gitbook would do:

Using Lodash introduces a vulnerability

I have Snyk check on my project and it reported an issue with this plugin using Lodash (as a dependency of jsdom).

MEDIUM SEVERITY EXPLOIT: PROOF OF CONCEPT
Prototype Pollution
Vulnerable module: lodash
Introduced through: [email protected]
Exploit maturity: Proof of concept
Reachability: No info
Detailed paths and remediation
Introduced through: [email protected] › [email protected] › [email protected] › [email protected] › [email protected] › [email protected]
Remediation: No remediation path available.
Overview
lodash is a modern JavaScript utility library delivering modularity, performance, & extras.

Affected versions of this package are vulnerable to Prototype Pollution. The function zipObjectDeep can be tricked into adding or modifying properties of the Object prototype. These properties will be present on all objects.