Skip to content

Support external linkage #11

@Blacksmoke16

Description

@Blacksmoke16

For Athena, things are currently setup where each component is its own mkdocs project via their projects plugin. This is usually fine, but now that I'm getting a bit more into cross-component usage, I'd like to improve things a bit.

The main use case I'm wanting to support is the ability to define logic somewhere to have the generated HTML include an a tag to some external location.

Take this method for example:

Image ACON::Output::Interface links just fine because it's defined in the Console component of course. However this component also depends on the Clock component, whose types are not linked.

The logic would be something like:

# Grab the `site_name` config value currently building.
current_component = mkdocs_gen_files.config.get('site_name')

# Do some light validation.
# Might also need some code to handle the aliases, but you get the idea.
if current_component is None:
  return text

if '::' not in text:
  return text

type_component = text.split('::')[1]

# Manually create a doc link if a type is from another component.
# E.g. `'Console' != 'Clock'`
if current_component != type_component:
  href = '/'.join(text.split('::')[1:])
  return Markup('<a href="/{}">{}</a>').format(href, text)

Having a callback that gets called for every type that fails to lookup would be great. Then could maybe have the link code check for some new external_href property and if set, use it. Otherwise fallback on the raw text like it does now.

The reason I want it to work this way is so that I don't have to try and merge the docs for n different components. I.e. this way each component's docs stay in their own project and the user can just navigate between them, using back button to go back if they wish.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions