diff --git a/README.md b/README.md
index 77f9a6f..5a36484 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Markdown Refdocs
 
-![build](https://github.com/creisle/markdown_refdocs/workflows/build/badge.svg?branch=master) [![PyPi](https://img.shields.io/pypi/v/markdown_refdocs.svg)](https://pypi.org/project/markdown-refdocs) [![codecov](https://codecov.io/gh/creisle/markdown_refdocs/branch/master/graph/badge.svg)](https://codecov.io/gh/creisle/markdown_refdocs)
+![build](https://github.com/creisle/markdown_refdocs/workflows/build/badge.svg) [![PyPi](https://img.shields.io/pypi/v/markdown_refdocs.svg)](https://pypi.org/project/markdown-refdocs) [![codecov](https://codecov.io/gh/creisle/markdown_refdocs/branch/master/graph/badge.svg)](https://codecov.io/gh/creisle/markdown_refdocs)
 
 Extracts docstings and type annotations from a python package to generate reference documentation in markdown.
 See an example of this at: https://creisle.github.io/markdown_refdocs/
diff --git a/markdown_refdocs/links.py b/markdown_refdocs/links.py
index 0dfcc6f..691b43b 100644
--- a/markdown_refdocs/links.py
+++ b/markdown_refdocs/links.py
@@ -8,6 +8,9 @@ from .types import ParsedModule
 def create_types_mapping(modules: Dict[str, ParsedModule]) -> Dict[str, str]:
     """
     Creates mapping of type name to links
+
+    Note:
+        This only links within a package
     """
     simple_mapping: Dict[str, Optional[str]] = {}
     qualified_mapping: Dict[str, Optional[str]] = {}
diff --git a/markdown_refdocs/markdown.py b/markdown_refdocs/markdown.py
index 2651c6d..fc28fd9 100644
--- a/markdown_refdocs/markdown.py
+++ b/markdown_refdocs/markdown.py
@@ -1,50 +1,28 @@
 import re
-from itertools import permutations
-from typing import Dict, Tuple
-
-from .types import ParsedClass, ParsedFunction, ParsedModule, ParsedVariable
-
-
-def _create_type_link(type_name: str, types_links: Dict[str, str] = {}) -> Tuple[str, bool]:
-    m = re.match(r'^Optional\[(.*)\]$', type_name)
-    if m:
-        inner_link, contains_link = _create_type_link(m.group(1), types_links)
-        if contains_link:
-            return f'Optional\\[{inner_link}\\]', True
-    if type_name in types_links:
-        return f'[{type_name}]({types_links[type_name]})', True
-
-    for typing_type in ['Dict', 'List', 'Iterable', 'Set', 'Optional']:
-        for link_type in types_links:
-            if f'{typing_type}[{link_type}]' == type_name:
-                inner_link, contains_link = _create_type_link(link_type, types_links)
-                if contains_link:
-                    return f'{typing_type}\\[{inner_link}\\]', True
-
-    for typing_type in ['str', 'Tuple', 'int']:
-        for link_type in types_links:
-            if f'Dict[{typing_type}, {link_type}]' == type_name:
-                inner_link, contains_link = _create_type_link(link_type, types_links)
-                if contains_link:
-                    return f'Dict\\[`{typing_type}`, {inner_link}\\]', True
-
-    for typing_type in ['Union', 'Tuple']:
-        for first, second in permutations(types_links.keys(), 2):
-            double_link = f'{typing_type}[{first}, {second}]'
-            if double_link == type_name:
-                first_link, contains_link = _create_type_link(first, types_links)
-                second_link, contains_other_link = _create_type_link(second, types_links)
-                if contains_link or contains_other_link:
-                    return f'{typing_type}\\[{first_link}, {second_link}\\]', True
-
-    return type_name, False
+from typing import Dict, List
+
+from .types import ParsedClass, ParsedFunction, ParsedModule, ParsedVariable, ADMONITIONS
 
 
 def create_type_link(type_name: str, types_links: Dict[str, str] = {}) -> str:
-    type_link, has_link = _create_type_link(type_name, types_links)
-    if not has_link:
-        return f'`{type_link}`'
-    return type_link
+    tokens = re.split(r'(\[|\]|\s|,)', str(type_name))
+
+    linked = []
+    contains_link = False
+    for token in tokens:
+        if token in types_links:
+            contains_link = True
+            linked.append(f'[{token}]({types_links[token]})')
+        elif token in ['str', 'int', 'bool', 'float']:
+            linked.append(f'`{token}`')
+        elif token in [']', '[']:
+            linked.append(f'\\{token}')
+        else:
+            linked.append(token)
+
+    if not contains_link:
+        return f'`{type_name}`'
+    return ''.join(linked)
 
 
 def argument_md(
@@ -74,6 +52,17 @@ def argument_md(
     return md
 
 
+def admonitions_to_markdown(parsed: Dict[str, List[str]]) -> str:
+    md: List[str] = []
+    for admonition in ADMONITIONS:
+        if parsed.get(admonition, []):
+            md.append(f'!!! {admonition}')
+            for line in parsed[admonition]:
+                md.append(f'\t{line}')
+            md.append('')
+    return '\n'.join(md)
+
+
 def function_to_markdown(
     parsed: ParsedFunction, heading_level: int = 2, types_links: Dict[str, str] = {}
 ) -> str:
@@ -113,6 +102,10 @@ def function_to_markdown(
             md.append(f'```python\n{example}\n```\n')
         md.append('')
 
+    admon_md = admonitions_to_markdown(parsed)
+    if admon_md:
+        md.append(admon_md)
+
     return '\n'.join(md)
 
 
@@ -138,6 +131,10 @@ def class_to_markdown(parsed: ParsedClass, types_links: Dict[str, str] = {}) ->
             md.append(argument_md(types_links=types_links, **attr))
         md.append('')
 
+    admon_md = admonitions_to_markdown(parsed)
+    if admon_md:
+        md.append(admon_md)
+
     if parsed.get('functions', ''):
         for func in parsed['functions']:
             md.append(function_to_markdown(func, heading_level=3, types_links=types_links))
diff --git a/markdown_refdocs/parsers.py b/markdown_refdocs/parsers.py
index 3ce944e..2ab1d7f 100644
--- a/markdown_refdocs/parsers.py
+++ b/markdown_refdocs/parsers.py
@@ -1,7 +1,7 @@
 import re
 from typing import Any, Dict
 
-from .types import ParsedDocstring, ParsedParameter, ParsedReturn
+from .types import ParsedDocstring, ParsedParameter, ParsedReturn, ADMONITIONS
 
 
 def left_align_block(block: str) -> str:
@@ -9,7 +9,7 @@ def left_align_block(block: str) -> str:
     if not lines:
         return block
 
-    indent = re.match(r'(\s*).*', lines[0]).group(1)
+    indent = re.match(r'(\s*).*', lines[0]).group(1)  # type: ignore
     content = '\n'.join([line[len(indent) :] for line in lines])
     return content
 
@@ -21,7 +21,7 @@ def parse_google_docstring(
     parses a google-style docsting into a dictionary of the various sections
     """
     state = None
-    tags = ['args', 'returns', 'raises', 'note', 'desc', 'example', 'attributes']
+    tags = ['args', 'returns', 'raises', 'note', 'desc', 'example', 'attributes', 'warning']
     content: Dict[str, Any] = {tag: [] for tag in tags}
 
     docstring = (docstring if docstring else '').strip()
@@ -66,7 +66,7 @@ def parse_google_docstring(
         parsed_args = []
         for i, arg in enumerate(content[tag]):
             try:
-                name, _, arg_type, arg_desc = re.match(
+                name, _, arg_type, arg_desc = re.match(  # type: ignore
                     r'^(\w+)(\s+\(([^)]+)\))?:\s*(.*)$', arg
                 ).groups()
                 parsed_args.append(
@@ -88,11 +88,11 @@ def parse_google_docstring(
             result[tag] = parsed_args
 
     for i, line in enumerate(content['raises']):
-        _, arg_type, arg_desc = re.match(r'^(([^:]+):)?\s*(.*)$', line).groups()
+        _, arg_type, arg_desc = re.match(r'^(([^:]+):)?\s*(.*)$', line).groups()  # type: ignore
         result['raises'].append(ParsedReturn({'type': arg_type, 'description': arg_desc}))
 
     for i, line in enumerate(content['returns']):
-        _, arg_type, arg_desc = re.match(r'^(([^:]+):)?\s*(.*)$', line).groups()
+        _, arg_type, arg_desc = re.match(r'^(([^:]+):)?\s*(.*)$', line).groups()  # type: ignore
         if result['returns']:
             result['returns']['description'] += ' ' + line
         else:
@@ -102,9 +102,12 @@ def parse_google_docstring(
             result['returns'] = ParsedReturn({'type': arg_type, 'description': arg_desc})
 
     result['description'] = '\n'.join(content['desc']).strip()
-    result['note'] = '\n'.join(content['note'])
 
     for i, example in enumerate(content['example']):
         result['examples'].append(left_align_block('\n'.join(example)))
 
+    for admon in ADMONITIONS:
+        if content.get(admon, []):
+            result[admon] = content[admon]
+
     return result
diff --git a/markdown_refdocs/types.py b/markdown_refdocs/types.py
index 537adb4..cb70fe0 100644
--- a/markdown_refdocs/types.py
+++ b/markdown_refdocs/types.py
@@ -63,3 +63,6 @@ class ParsedModule(Parsed):
     classes: List[ParsedClass]
     functions: List[ParsedFunction]
     variables: List[ParsedVariable]
+
+
+ADMONITIONS = ['warning', 'note', 'info', 'bug', 'tip', 'question', 'failure', 'danger', 'quote']
diff --git a/mkdocs.yml b/mkdocs.yml
index 164f786..3546cad 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -9,6 +9,7 @@ nav:
       - markdown_refdocs.links: reference/markdown_refdocs/links.md
 markdown_extensions:
   - codehilite
+  - admonition
 theme:
   name: "material"
 repo_url: https://github.com/creisle/markdown_refdocs.git

Error generating reference docs for MAVIS
Encountered this error generating reference docs from the [mavis](https://github.com/bcgsc/mavis) package
```
Traceback (most recent call last):
  File "/Users/creisle/git/markdown_refdocs/venv/bin/markdown_refdocs", line 11, in <module>
    load_entry_point('markdown-refdocs', 'console_scripts', 'markdown_refdocs')()
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/main.py", line 508, in command_interface
    namespace_headers=args.namespace_headers,
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/main.py", line 461, in extract_to_markdown
    fh.write(module_to_markdown(parsed, relative_mapping))
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 175, in module_to_markdown
    md.append(class_to_markdown(cls, types_links=types_links))
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 127, in class_to_markdown
    + ' '.join([create_type_link(t, types_links) for t in parsed['inherits']]),
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 127, in <listcomp>
    + ' '.join([create_type_link(t, types_links) for t in parsed['inherits']]),
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 44, in create_type_link
    type_link, has_link = _create_type_link(type_name, types_links)
  File "/Users/creisle/git/markdown_refdocs/markdown_refdocs/markdown.py", line 9, in _create_type_link
    m = re.match(r'^Optional\[(.*)\]$', type_name)
  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.7/lib/python3.7/re.py", line 173, in match
    return _compile(pattern, flags).match(string)
TypeError: expected string or bytes-like object
```
diff --git a/tests/test_main.py b/tests/test_main.py
index 9600efd..bd0ca72 100644
--- a/tests/test_main.py
+++ b/tests/test_main.py
@@ -4,7 +4,7 @@ from unittest.mock import mock_open, patch
 
 from markdown_refdocs.main import command_interface, parse_module_file
 from markdown_refdocs.markdown import module_to_markdown
-from markdown_refdocs.types import ParsedModule, ParsedVariable
+from markdown_refdocs.types import ParsedVariable
 
 
 class TestParseModuleFile:
@@ -284,7 +284,6 @@ say something
                     'hidden': False,
                     'functions': [],
                     'examples': [],
-                    'note': '',
                     'attributes': [
                         {
                             'hidden': False,
@@ -550,10 +549,9 @@ class SomeType(TypedDict):
                     'description': '',
                     'hidden': False,
                     'examples': [],
-                    'note': '',
                     'attributes': [
-                        {'name': 'name', 'type': 'str', 'source_code': 'name: str',},
-                        {'name': 'parent', 'type': 'str', 'source_code': 'parent: str',},
+                        {'name': 'name', 'type': 'str', 'source_code': 'name: str'},
+                        {'name': 'parent', 'type': 'str', 'source_code': 'parent: str'},
                         {'name': 'grandparent', 'type': 'str', 'source_code': 'grandparent: str',},
                     ],
                     'functions': [],
@@ -603,7 +601,6 @@ class SomeType(TypedDict):
                     'name': 'SomeType',
                     'description': '',
                     'inherits': ['TypedDict'],
-                    'note': '',
                     'examples': [],
                     'hidden': False,
                     'functions': [],
diff --git a/tests/test_markdown.py b/tests/test_markdown.py
index 57d1253..0c059b7 100644
--- a/tests/test_markdown.py
+++ b/tests/test_markdown.py
@@ -75,3 +75,15 @@ class TestCreateTypeLink:
         types = {'type': link}
         md = create_type_link('List[type]', types)
         assert md == f'List\\[[type]({link})\\]'
+
+    def test_linking_as_dict_target(self):
+        link = './path/to/other/#class-someclass'
+        types = {'type': link}
+        md = create_type_link('Dict[str, type]', types)
+        assert md == f'Dict\\[`str`, [type]({link})\\]'
+
+    def test_tuple_of_links(self):
+        link = './path/to/other/#class-someclass'
+        types = {'type': link}
+        md = create_type_link('Tuple[type, type]', types)
+        assert md == f'Tuple\\[[type]({link}), [type]({link})\\]'

pip install -e .[dev]
parse_log_pytest
pytest
pytest flake8
apt-get update apt-get install -y gcc
3.9
pytest --no-header -rA --tb=line --color=no -p no:cacheprovider -W ignore::DeprecationWarning
attrs==25.3.0
babel==2.17.0
backports.tarfile==1.2.0
backrefs==5.8
black==25.1.0
certifi==2025.1.31
cffi==1.17.1
charset-normalizer==3.4.1
click==8.1.8
colorama==0.4.6
coverage==7.8.0
cryptography==44.0.2
docutils==0.21.2
exceptiongroup @ file:///croot/exceptiongroup_1706031385326/work
flake8==7.2.0
flake8-annotations==3.1.1
ghp-import==2.1.0
id==1.5.0
idna==3.10
importlib_metadata==8.6.1
iniconfig @ file:///home/linux1/recipes/ci/iniconfig_1610983019677/work
jaraco.classes==3.4.0
jaraco.context==6.0.1
jaraco.functools==4.1.0
jeepney==0.9.0
Jinja2==3.1.6
keyring==25.6.0
Markdown==3.7
markdown-it-py==3.0.0
-e git+https://github.com/creisle/markdown_refdocs.git@57d9f12b559073824044bc6b708aa6fe3c928fa6#egg=markdown_refdocs
MarkupSafe==3.0.2
mccabe==0.7.0
mdurl==0.1.2
mergedeep==1.3.4
mkdocs==1.6.1
mkdocs-get-deps==0.2.0
mkdocs-material==9.6.10
mkdocs-material-extensions==1.3.1
more-itertools==10.6.0
mypy==1.15.0
mypy-extensions==1.0.0
nh3==0.2.21
packaging @ file:///croot/packaging_1734472117206/work
paginate==0.5.7
pathspec==0.12.1
platformdirs==4.3.7
pluggy @ file:///croot/pluggy_1733169602837/work
pycodestyle==2.13.0
pycparser==2.22
pyflakes==3.3.2
Pygments==2.19.1
pymdown-extensions==10.14.3
pytest @ file:///croot/pytest_1738938843180/work
pytest-cov==6.0.0
pytest-runner==6.0.1
python-dateutil==2.9.0.post0
PyYAML==6.0.2
pyyaml_env_tag==0.1
readme_renderer==44.0
requests==2.32.3
requests-toolbelt==1.0.0
rfc3986==2.0.0
rich==14.0.0
SecretStorage==3.3.3
six==1.17.0
tomli @ file:///opt/conda/conda-bld/tomli_1657175507142/work
twine==6.1.0
typing_extensions==4.13.0
urllib3==2.3.0
watchdog==6.0.0
zipp==3.21.0

name: markdown_refdocs
channels:
  - defaults
  - https://repo.anaconda.com/pkgs/main
  - https://repo.anaconda.com/pkgs/r
  - conda-forge
dependencies:
  - _libgcc_mutex=0.1=main
  - _openmp_mutex=5.1=1_gnu
  - ca-certificates=2025.2.25=h06a4308_0
  - exceptiongroup=1.2.0=py39h06a4308_0
  - iniconfig=1.1.1=pyhd3eb1b0_0
  - ld_impl_linux-64=2.40=h12ee557_0
  - libffi=3.4.4=h6a678d5_1
  - libgcc-ng=11.2.0=h1234567_1
  - libgomp=11.2.0=h1234567_1
  - libstdcxx-ng=11.2.0=h1234567_1
  - ncurses=6.4=h6a678d5_0
  - openssl=3.0.16=h5eee18b_0
  - packaging=24.2=py39h06a4308_0
  - pip=25.0=py39h06a4308_0
  - pluggy=1.5.0=py39h06a4308_0
  - pytest=8.3.4=py39h06a4308_0
  - python=3.9.21=he870216_1
  - readline=8.2=h5eee18b_0
  - setuptools=75.8.0=py39h06a4308_0
  - sqlite=3.45.3=h5eee18b_0
  - tk=8.6.14=h39e8969_0
  - tomli=2.0.1=py39h06a4308_0
  - tzdata=2025a=h04d1e81_0
  - wheel=0.45.1=py39h06a4308_0
  - xz=5.6.4=h5eee18b_1
  - zlib=1.2.13=h5eee18b_1
  - pip:
      - attrs==25.3.0
      - babel==2.17.0
      - backports-tarfile==1.2.0
      - backrefs==5.8
      - black==25.1.0
      - certifi==2025.1.31
      - cffi==1.17.1
      - charset-normalizer==3.4.1
      - click==8.1.8
      - colorama==0.4.6
      - coverage==7.8.0
      - cryptography==44.0.2
      - docutils==0.21.2
      - flake8==7.2.0
      - flake8-annotations==3.1.1
      - ghp-import==2.1.0
      - id==1.5.0
      - idna==3.10
      - importlib-metadata==8.6.1
      - jaraco-classes==3.4.0
      - jaraco-context==6.0.1
      - jaraco-functools==4.1.0
      - jeepney==0.9.0
      - jinja2==3.1.6
      - keyring==25.6.0
      - markdown==3.7
      - markdown-it-py==3.0.0
      - markupsafe==3.0.2
      - mccabe==0.7.0
      - mdurl==0.1.2
      - mergedeep==1.3.4
      - mkdocs==1.6.1
      - mkdocs-get-deps==0.2.0
      - mkdocs-material==9.6.10
      - mkdocs-material-extensions==1.3.1
      - more-itertools==10.6.0
      - mypy==1.15.0
      - mypy-extensions==1.0.0
      - nh3==0.2.21
      - paginate==0.5.7
      - pathspec==0.12.1
      - platformdirs==4.3.7
      - pycodestyle==2.13.0
      - pycparser==2.22
      - pyflakes==3.3.2
      - pygments==2.19.1
      - pymdown-extensions==10.14.3
      - pytest-cov==6.0.0
      - pytest-runner==6.0.1
      - python-dateutil==2.9.0.post0
      - pyyaml==6.0.2
      - pyyaml-env-tag==0.1
      - readme-renderer==44.0
      - requests==2.32.3
      - requests-toolbelt==1.0.0
      - rfc3986==2.0.0
      - rich==14.0.0
      - secretstorage==3.3.3
      - six==1.17.0
      - twine==6.1.0
      - typing-extensions==4.13.0
      - urllib3==2.3.0
      - watchdog==6.0.0
      - zipp==3.21.0
prefix: /opt/conda/envs/markdown_refdocs

tests/test_main.py::TestParseModuleFile::test_class_desc tests/test_main.py::TestParseModuleFile::test_typed_dict tests/test_main.py::TestParseModuleFile::test_typed_dict_with_docstring tests/test_markdown.py::TestCreateTypeLink::test_tuple_of_links
tests/test_main.py::TestParseModuleFile::test_nested_return_type_annotation tests/test_main.py::TestParseModuleFile::test_complex_types tests/test_main.py::TestParseModuleFile::test_callable tests/test_main.py::TestCommandInterface::test_package_path
tests/test_main.py::TestParseModuleFile::test_multiple_decorators tests/test_main.py::TestParseModuleFile::test_simple_module tests/test_main.py::TestParseModuleFile::test_overwrite_docstring_with_annotations tests/test_main.py::TestParseModuleFile::test_examples_from_docstring tests/test_main.py::TestParseModuleFile::test_returns_from_type_annotation tests/test_main.py::TestParseModuleFile::test_parses_raise tests/test_main.py::TestParseModuleFile::test_multiline_function_def tests/test_main.py::TestParseModuleFile::test_class_methods tests/test_main.py::TestParseModuleFile::test_pass_class_args_to_construcor tests/test_main.py::TestParseModuleFile::test_module_constant tests/test_main.py::TestParseModuleFile::test_module_constant_pulled_when_any_docstring tests/test_main.py::TestParseModuleFile::test_multiline_module_constant tests/test_main.py::TestParseModuleFile::test_namespaced_types tests/test_main.py::TestParseModuleFile::test_alternate_typeddict_notation tests/test_main.py::TestParseModuleFile::test_multiline_docstring_desc tests/test_markdown.py::TestConstantToMarkdown::test_no_source_code tests/test_markdown.py::TestConstantToMarkdown::test_has_source_code tests/test_markdown.py::TestFunctionToMarkdown::test_has_docstring_no_params tests/test_markdown.py::TestFunctionToMarkdown::test_long_docstring tests/test_markdown.py::TestCreateTypeLink::test_simple_link tests/test_markdown.py::TestCreateTypeLink::test_link_inside_list tests/test_markdown.py::TestCreateTypeLink::test_linking_as_dict_target
markdown_refdocs/parsers.py markdown_refdocs/types.py markdown_refdocs/markdown.py markdown_refdocs/links.py mkdocs.yml README.md
markdown_refdocs/parsers.py markdown_refdocs/types.py markdown_refdocs/markdown.py markdown_refdocs/links.py mkdocs.yml README.md