[
)](https://badge.fury.io/py/markdown_javadoc_references)
# 🐍 Python Markdown Javadoc References
Have you ever been tired of copying entire Javadoc URLs into your Markdown just to link to the documentation for some Java classes?
That is where is extension comes in handy!
This [python markdown extension](https://github.com/Python-Markdown/markdown) adds the ability to directly reference [Java](https://www.java.com/de/) classes, methods and fields in
your markdown to link to their documentation. It supports both Javadoc prior to Java 9 and from Java 9 onwards.
## Installation
You can find the [extension on PyPi](https://pypi.org/project/markdown_javadoc_references/) under `markdown_javadoc_references`.
### With plain [python markdown](https://github.com/jackdewinter/pymarkdown)
To use this extension with the API of [python markdown](https://github.com/jackdewinter/pymarkdown), just add
`JavaDocRefExtension` to the list of your extensions and provide the URLs to use.
```python
import markdown
from markdown_javadoc_references import JavaDocRefExtension
urls = [
'https://docs.oracle.com/en/java/javase/24/docs/api/',
{
'alias': 'jdk8',
'url': 'https://docs.oracle.com/javase/8/docs/api/'
}
]
text = 'your markdown text with reference [String][java.lang.String]'
result = markdown.markdown(text, extensions=[JavaDocRefExtension(urls=urls)])
```
### With [MkDocs](https://www.mkdocs.org/)
To use this extension with [MkDocs](https://www.mkdocs.org/) just add it to your `mkdocs.yml`:
```yaml
markdown_extensions:
- markdown_javadoc_references:
- urls:
- 'https://docs.oracle.com/en/java/javase/24/docs/api/'
- alias: 'jdk8'
url: 'https://docs.oracle.com/javase/8/docs/api/'
```
## Usage
Referencing java methods, classes or fields is similar to how it is done in normal (markdown) javadoc comments,
with the slight change of double `[` and `]` in the second part of the reference.
For example
`[String#concat(String)][[String#concat(String)]]` will result in [String#concat(String)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#concat(java.lang.String))
### Autolinks
Often times the text presented to the user can be easily derived from the used reference.
For this common case you can use the autolink syntax to avoid writing it twice.
`<String#concat(String)>` is the same as `[String#concat(String)][[String#concat(String)]]`
#### Formatting
By default, the text that is presented to the user is the reference with the packages stripped.
For example:
- `<java.lang.String>` -> `[String][[java.lang.String]])`
- `<java.lang.String#concat(java.lang.String)>` -> `[String#concat(String)][[java.lang.String#concat(java.lang.String)]]`
- `<java.lang.String#CASE_INSENSITIVE_ORDER` -> `[String#CASE_INSENSITIVE_ORDER][[java.lang.String#CASE_INSENSITIVE_ORDER]]`
To configure how the text is derived, you can provide a small python script via the config key `autolink-format`.
In this environment, you can use the `ref` variable to get the resolved [reference entity](src/markdown_javadoc_references/entities.py).
Now you can just use a `match` construct to define the specific formatting for each entity type.
The provided code then should just `return` the string presented to the user.
The (class) names `Klass`, `Field`, `Method` and `Type` are automatically imported for you. Please take a look at the [source code](src/markdown_javadoc_references/entities.py)
to learn more about the data and utility functions of each entity. You need some basic python programming skills to do this (or just ask ChatGPT).
> [!NOTE]
> The content of this config option will be copied in as the body of a python function.
Example (default formatter):
```python
match ref:
case Klass():
return f"@{ref.name}" if ref.type == Type.ANN_INTERFACE else ref.name
case Field():
return f'{ref.klass.name}#{ref.name}'
case Method():
return f'{ref.klass.name}#{ref.name}({ref.parameter_names_joined()})'
```
Or in the `mkdocs.yml`:
```yaml
markdown_extensions:
- markdown_javadoc_references:
- urls:
- 'https://docs.oracle.com/en/java/javase/24/docs/api/'
- autolink-format: |
match ref:
case Klass():
return ref.name
case Field():
return f'{ref.klass.name}#{ref.name}'
case Method():
return f'{ref.klass.name}#{ref.name}({ref.parameter_names_joined()})'
```
### Classes
To just reference a class you only need to provide its name:
`<String>`. If multiple classes with this name exists, just add a [package](#packages) or [url alias](#url-aliases).
### Methods
To reference methods you provide the classname and method name following its parameters separated by `#`:
`<String#conact(String)`.
Again, if multiple javadocs are matched just add a [url alias](#url-aliases) or [packages](#packages) to parameters
or the enclosing class.
### Packages
To clarify which class to use, you can add a package in front of it:
`<java.lang.String>`.
Furthermore, you can also a package to method parameters:
`<String#concact(java.lang.String)`
> [!WARNING]
> If multiple matches are found for a reference, the reference will be marked as "Invalid"!
### Fields
Like methods, fields can be referred to in a similar style `<String#CASE_INSENSITIVE_ORDER>` will link to [String#CASE_INSENSITIVE_ORDER](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#CASE_INSENSITIVE_ORDER)
### Constructors
To refer to constructors, just add `<init>` in the place where the method name would be:
`String#<init>(byte[],int,int)` will link to [String#<init>(byte[],int,int)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#%3Cinit%3E(byte%5B%5D,int,int))
### URL aliases
Instead of stating the package explicitly, you can also add a URL alias to your reference.
For that to work, you have to state the alias for your javadoc site in your [configuration. (take a look at installation)](#installation)
Assuming you have a javadoc site configured with the alias "jdk8":
```yaml
markdown_extensions:
- markdown_javadoc_references:
- urls:
- 'https://docs.oracle.com/en/java/javase/24/docs/api/'
- alias: 'jdk8'
url: 'https://docs.oracle.com/javase/8/docs/api/'
```
you can now use this alias to force the extension to only search under the site `https://docs.oracle.com/javase/8/docs/api/`
for the referred to javadoc: `<jdk8 -> String#<init>(byte[],int,int)>`
Additionally, if you don't have an alias configured explicitly, you can still use the whole URL:
`<https://docs.oracle.com/en/java/javase/24/docs/api/ -> String#<init>(byte[],int,int)>`
> [!IMPORTANT]
> The URL has to be still mentioned in the configuration!
Raw data
{
"_id": null,
"home_page": null,
"name": "markdown_javadoc_references",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "markdown, markdown-extension, mkdocs, mkdocs-plugin, documentation, javadoc, java, references, links, markdown links, javadoc links, java-references, api-docs, docs, doc-links",
"author": "Nick Hensel",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5d/b6/adf95257c227df54809652d51557bce076a8e261c520fd105d58a43901f7/markdown_javadoc_references-0.3.5.tar.gz",
"platform": null,
"description": "[\n)](https://badge.fury.io/py/markdown_javadoc_references)\n# \ud83d\udc0d Python Markdown Javadoc References\nHave you ever been tired of copying entire Javadoc URLs into your Markdown just to link to the documentation for some Java classes?\nThat is where is extension comes in handy! \n\nThis [python markdown extension](https://github.com/Python-Markdown/markdown) adds the ability to directly reference [Java](https://www.java.com/de/) classes, methods and fields in \nyour markdown to link to their documentation. It supports both Javadoc prior to Java 9 and from Java 9 onwards.\n\n## Installation\nYou can find the [extension on PyPi](https://pypi.org/project/markdown_javadoc_references/) under `markdown_javadoc_references`.\n\n### With plain [python markdown](https://github.com/jackdewinter/pymarkdown)\nTo use this extension with the API of [python markdown](https://github.com/jackdewinter/pymarkdown), just add\n`JavaDocRefExtension` to the list of your extensions and provide the URLs to use.\n\n```python\nimport markdown\nfrom markdown_javadoc_references import JavaDocRefExtension\n\nurls = [\n 'https://docs.oracle.com/en/java/javase/24/docs/api/',\n {\n 'alias': 'jdk8',\n 'url': 'https://docs.oracle.com/javase/8/docs/api/'\n }\n]\n\ntext = 'your markdown text with reference [String][java.lang.String]'\nresult = markdown.markdown(text, extensions=[JavaDocRefExtension(urls=urls)])\n```\n\n\n### With [MkDocs](https://www.mkdocs.org/)\nTo use this extension with [MkDocs](https://www.mkdocs.org/) just add it to your `mkdocs.yml`:\n\n```yaml\nmarkdown_extensions:\n - markdown_javadoc_references:\n - urls:\n - 'https://docs.oracle.com/en/java/javase/24/docs/api/'\n - alias: 'jdk8'\n url: 'https://docs.oracle.com/javase/8/docs/api/'\n```\n\n## Usage\nReferencing java methods, classes or fields is similar to how it is done in normal (markdown) javadoc comments,\nwith the slight change of double `[` and `]` in the second part of the reference.\nFor example\n`[String#concat(String)][[String#concat(String)]]` will result in [String#concat(String)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#concat(java.lang.String))\n\n### Autolinks\nOften times the text presented to the user can be easily derived from the used reference.\nFor this common case you can use the autolink syntax to avoid writing it twice.\n\n`<String#concat(String)>` is the same as `[String#concat(String)][[String#concat(String)]]`\n\n#### Formatting\nBy default, the text that is presented to the user is the reference with the packages stripped.\n\nFor example:\n- `<java.lang.String>` -> `[String][[java.lang.String]])`\n- `<java.lang.String#concat(java.lang.String)>` -> `[String#concat(String)][[java.lang.String#concat(java.lang.String)]]`\n- `<java.lang.String#CASE_INSENSITIVE_ORDER` -> `[String#CASE_INSENSITIVE_ORDER][[java.lang.String#CASE_INSENSITIVE_ORDER]]`\n\nTo configure how the text is derived, you can provide a small python script via the config key `autolink-format`.\nIn this environment, you can use the `ref` variable to get the resolved [reference entity](src/markdown_javadoc_references/entities.py).\nNow you can just use a `match` construct to define the specific formatting for each entity type.\n\nThe provided code then should just `return` the string presented to the user. \nThe (class) names `Klass`, `Field`, `Method` and `Type` are automatically imported for you. Please take a look at the [source code](src/markdown_javadoc_references/entities.py)\nto learn more about the data and utility functions of each entity. You need some basic python programming skills to do this (or just ask ChatGPT).\n\n> [!NOTE]\n> The content of this config option will be copied in as the body of a python function.\n\nExample (default formatter):\n```python \nmatch ref:\n case Klass():\n return f\"@{ref.name}\" if ref.type == Type.ANN_INTERFACE else ref.name\n case Field():\n return f'{ref.klass.name}#{ref.name}'\n case Method():\n return f'{ref.klass.name}#{ref.name}({ref.parameter_names_joined()})'\n```\n\nOr in the `mkdocs.yml`:\n```yaml\nmarkdown_extensions:\n - markdown_javadoc_references:\n - urls:\n - 'https://docs.oracle.com/en/java/javase/24/docs/api/'\n - autolink-format: |\n match ref:\n case Klass():\n return ref.name\n case Field():\n return f'{ref.klass.name}#{ref.name}'\n case Method():\n return f'{ref.klass.name}#{ref.name}({ref.parameter_names_joined()})'\n```\n\n### Classes\nTo just reference a class you only need to provide its name:\n`<String>`. If multiple classes with this name exists, just add a [package](#packages) or [url alias](#url-aliases).\n\n### Methods\nTo reference methods you provide the classname and method name following its parameters separated by `#`:\n`<String#conact(String)`.\n\nAgain, if multiple javadocs are matched just add a [url alias](#url-aliases) or [packages](#packages) to parameters\nor the enclosing class.\n\n### Packages\nTo clarify which class to use, you can add a package in front of it:\n`<java.lang.String>`.\n\nFurthermore, you can also a package to method parameters:\n`<String#concact(java.lang.String)`\n\n> [!WARNING]\n> If multiple matches are found for a reference, the reference will be marked as \"Invalid\"!\n\n### Fields\nLike methods, fields can be referred to in a similar style `<String#CASE_INSENSITIVE_ORDER>` will link to [String#CASE_INSENSITIVE_ORDER](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#CASE_INSENSITIVE_ORDER)\n\n### Constructors\nTo refer to constructors, just add `<init>` in the place where the method name would be:\n`String#<init>(byte[],int,int)` will link to [String#<init>(byte[],int,int)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#%3Cinit%3E(byte%5B%5D,int,int))\n\n### URL aliases\nInstead of stating the package explicitly, you can also add a URL alias to your reference.\nFor that to work, you have to state the alias for your javadoc site in your [configuration. (take a look at installation)](#installation)\n\nAssuming you have a javadoc site configured with the alias \"jdk8\":\n```yaml\nmarkdown_extensions:\n - markdown_javadoc_references:\n - urls:\n - 'https://docs.oracle.com/en/java/javase/24/docs/api/'\n - alias: 'jdk8'\n url: 'https://docs.oracle.com/javase/8/docs/api/'\n```\n\nyou can now use this alias to force the extension to only search under the site `https://docs.oracle.com/javase/8/docs/api/`\nfor the referred to javadoc: `<jdk8 -> String#<init>(byte[],int,int)>` \n\nAdditionally, if you don't have an alias configured explicitly, you can still use the whole URL:\n`<https://docs.oracle.com/en/java/javase/24/docs/api/ -> String#<init>(byte[],int,int)>`\n\n> [!IMPORTANT]\n> The URL has to be still mentioned in the configuration!",
"bugtrack_url": null,
"license": null,
"summary": "A Markdown extension that makes it easy to reference Javadocs",
"version": "0.3.5",
"project_urls": {
"github": "https://github.com/Goldmensch/pymarkdown-java-references"
},
"split_keywords": [
"markdown",
" markdown-extension",
" mkdocs",
" mkdocs-plugin",
" documentation",
" javadoc",
" java",
" references",
" links",
" markdown links",
" javadoc links",
" java-references",
" api-docs",
" docs",
" doc-links"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b8901f7ff58c9fe9e8288e8ff6e98ad321ba686c87b728df380bbb2416518419",
"md5": "4e916707c04e0cf77b3eee8fa2fc3583",
"sha256": "92d2f6ee1536e376f55eb434f6b99def231acc7d124518ffef31ac0932ede6b7"
},
"downloads": -1,
"filename": "markdown_javadoc_references-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e916707c04e0cf77b3eee8fa2fc3583",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16187,
"upload_time": "2025-10-06T21:46:10",
"upload_time_iso_8601": "2025-10-06T21:46:10.128145Z",
"url": "https://files.pythonhosted.org/packages/b8/90/1f7ff58c9fe9e8288e8ff6e98ad321ba686c87b728df380bbb2416518419/markdown_javadoc_references-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5db6adf95257c227df54809652d51557bce076a8e261c520fd105d58a43901f7",
"md5": "279388ea1896ce68026c0eac07867bd0",
"sha256": "357f09f8afc9770de5ff487cdc85cdbe17be57b0734f9f00f95a4cb381e0b688"
},
"downloads": -1,
"filename": "markdown_javadoc_references-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "279388ea1896ce68026c0eac07867bd0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13741,
"upload_time": "2025-10-06T21:46:11",
"upload_time_iso_8601": "2025-10-06T21:46:11.167327Z",
"url": "https://files.pythonhosted.org/packages/5d/b6/adf95257c227df54809652d51557bce076a8e261c520fd105d58a43901f7/markdown_javadoc_references-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 21:46:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Goldmensch",
"github_project": "pymarkdown-java-references",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "markdown_javadoc_references"
}
JSON
