xunnamius/typedoc-plugin-markdown

A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.

typedoc-plugin-markdown (dev fork)

This is a typedoc-plugin-markdown fork that makes some tiny tweaks that might get merged back upstream some day.

This fork is meant to be temporary. These are the pending PRs:

• #364 (beautify representation of destructured parameters)

Install

NEVER install packages from this project and their official versions at the same time!

Packages

The following packages from this monorepo are available for immediate installation:

typedoc-plugin-markdown

npm install --save-dev https://xunn.at/typedoc-plugin-markdown

Advanced installation

If you want to use a specific version of an available package from this monorepo, you can specify its release tag (without the prefix):

npm install --save-dev https://xunn.at/[email protected]

Any valid commit-ish can be specified after the "@", not just version tags.

If you don't want to rely on xunn.at, you can also install the package from GitHub directly.

Installing an official typedoc-plugin-markdown package vs this project

Being a temporary fork, this project does not publish any packages, so you cannot do npm install <package-name>.

This is because, to be an actual drop in replacement for an official typedoc-plugin-markdown package, this project needs to reuse their names (e.g. typedoc-plugin-markdown) to satisfy, for example, peer dependency requirements. Of course, only the real packages can be installed via their names, but we can get around that by using a url (e.g. "https://xunn.at/typedoc-plugin-markdown") in lieu of a version number in the consuming project's package.json:

{
  ...
  "devDependencies": {
    ...
    "typedoc-plugin-markdown": "https://xunn.at/typedoc-plugin-markdown"
    ...
  }
}

This is what the above command does for you automatically.

Fork Structure and Maintenance

This fork is structured to be automatically rebased onto upstream releases when they occur. To facilitate this, care must be taken when committing changes to this repo. Specifically:

• The HEAD of the main (or master if it's an older repo) branch MUST ALWAYS be the release: bump version commit. This allows the upstream synchronization script to do its job.
• All changes should happen on the main/master branch.
• Changes should be added to existing commits via git commit --amend and then force pushed via git push --force. If amending a pre-existing commit is not desirable for whatever reason, the new commit should be rebased under the release: bump version commit.
• Never make custom releases or mess with the fork-specific git tags. These are automatically managed by the upstream synchronization script.

For example, suppose we updated the README.md file and want to commit the changes:

git add README.md
git commit -m mergeme
git rebase -S -i HEAD~5 --no-verify
# Either make the mergeme commit a "fixup" to a pre-existing commit or
# reposition it to occur below HEAD
git push --force

Any changes between main/master and the latest upstream release will be minted into a new local release only after upstream makes a new release. Until then, any changes will only be visible to those utilizing the main/master branch directly.