Skip to content

Mkdocs plugin which displays links in a more elegant way. Links will automatically be populated with an image, description, fav icon, and title for the target website; or you can override the values to give your own.

License

Notifications You must be signed in to change notification settings

Aetherinox/mkdocs-link-embeds

Repository files navigation

Mkdocs Plugin

♾️ Link Embeds ♾️


Display embedded links in a more elegant and modern way with the use of markdown codeblocks. Supports automatically fetching website data, or allows for you to override various values.




Version Version Build Status Downloads Size Last Commit







About

This plugin requires mkdocs to function.

This plugin allows you to display embedded links in a more elegant and modern way with the use of markdown codeblocks. You may either specify a URL and let the plugin auto-fill in details such as the site description and title, or you can override the auto-generated values and add your own.






Documentation

If you wish to view the complete documentation for this plugin, including installation and usage; visit https://aetherinox.github.io/mkdocs-link-embeds/




Install

Install the package for this plugin by running the command:

pip install mkdocs-link-embeds-plugin

Once you install the package above, open your mkdocs.yml and add a few new lines:


plugins:
  - link-embeds:
      enabled: true
      name_default: "Untitled Link"
      desc_default: "No description found"
      image_default: "https://github.com/Aetherinox/mkdocs-link-embeds/assets/118329232/c0298d98-0910-4235-a88f-0c3e2f704ba7"
      image_disabled: false
      favicon_default: "https://github.com/Aetherinox/mkdocs-link-embeds/assets/118329232/b37da9c6-6f17-4c3f-9c94-c346a6f31bfa"
      favicon_disabled: false
      favicon_size: 25
      target: "blank"
      accent: "FFFFFF1A"
      verbose: false

extra_css:
  - path/to/link-embeds.css

Ensure you download the contents of mkdocs_link_embeds_plugin/resources/link-embeds.css and place the file in your mkdocs directory. It must be placed in the path you specified under extra_css in the mkdocs.yml config above.




Usage

Once you have installed this plugin, you may now create a new page in your mkdocs project and insert a new codeblock with the following syntax:


```embed
url:            https://github.com/mkdocs/mkdocs/releases
name:           Github: Download Mkdocs
desc:           MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. It is designed to be easy to use and can be extended with third-party themes, plugins, and Markdown extensions.
image:          https://github.com/Aetherinox/mkdocs-link-embeds/assets/118329232/98179e23-ce03-4101-a858-56db0cd0e8f0
favicon:        https://github.com/Aetherinox/mkdocs-link-embeds/assets/118329232/13a151b1-d7f9-4e27-909b-a26986ab0954
favicon_size:   25
target:         new
accent:         4C59BFE0
```

This plugin accepts numerous properties:

  • url: The URL to the link.
  • name: Name / Title to show at the top of each embed.
  • desc: A description of what the site is for.
  • image: Image to display on the left side of each embedded website.
  • favicon: Favicon to display at the bottom, next to the link.
  • favicon_size: Favicon size.
  • target: Determines whether link opens in new window or same window.
  • accent: Specify accent color for embedded link surrounding border

The only required value is url.


If you provide only the url, and leave the others out; the plugin will attempt to check if your URL is valid, and then auto-fetch the metadata for that website. It will be used to populate the fields you did not provide.


If you do provide values such as desc, name, or image; those user inputs will take priority over the automatically fetched values.



About

Mkdocs plugin which displays links in a more elegant way. Links will automatically be populated with an image, description, fav icon, and title for the target website; or you can override the values to give your own.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published