You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Welcome to the MkDocs Ultralytics Plugin documentation! 📄 This powerful plugin enhances your MkDocs-generated documentation with advanced SEO optimizations, interactive social elements, and structured data support. It automates the generation of meta tags, incorporates social sharing features, and adds JSON-LD structured data to elevate user engagement and improve your Markdown project's visibility on the web.
5
+
Welcome to the documentation for the MkDocs Ultralytics Plugin! 📄 This powerful plugin enhances your [MkDocs](https://www.mkdocs.org/)-generated documentation with advanced Search Engine Optimization (SEO) features, interactive social elements, and structured data support. It automates the generation of essential meta tags, incorporates social sharing capabilities, and adds [JSON-LD](https://json-ld.org/) structured data to elevate user engagement and improve your Markdown project's visibility on the web.
This plugin seamlessly integrates a variety of features into your MkDocs site:
16
+
This plugin seamlessly integrates a variety of valuable features into your MkDocs site:
12
17
13
-
-**Meta Tag Generation**: Creates meta description and image tags from the first paragraph and image on the page.
14
-
-**Keyword Customization**: Allows you to define meta keywords directly in your Markdown front matter.
15
-
-**Social Media Optimization**: Generates Open Graph and Twitter meta tags for improved sharing on social platforms.
16
-
-**Sharing Made Simple**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content.
17
-
-**Git Insights**: Gathers and displays git commit information, including dates and authors, within the page footer.
18
-
-**JSON-LD Support**: Adds structured data in JSON-LD format for better search engine integration.
19
-
-**FAQ Parsing**: Automatically parses FAQ sections and includes them in the structured data.
20
-
-**Customizable Styling**: Includes inline CSS for consistent styling across your documentation.
18
+
-**Meta Tag Generation**: Automatically creates meta description and image tags using the first paragraph and image found on each page, crucial for SEO and social previews.
19
+
-**Keyword Customization**: Allows you to define specific meta keywords directly within your Markdown front matter for targeted SEO.
20
+
-**Social Media Optimization**: Generates [Open Graph](https://ogp.me/) and [Twitter Card](https://developer.x.com/en/docs/x-for-websites/cards/overview/summary-card-with-large-image)meta tags to ensure your content looks great when shared on social platforms.
21
+
-**Simple Sharing**: Inserts convenient share buttons for Twitter and LinkedIn at the end of your content, encouraging readers to share.
22
+
-**Git Insights**: Gathers and displays [Git](https://git-scm.com/) commit information, including update dates and authors, directly within the page footer for transparency.
23
+
-**JSON-LD Support**: Adds structured data in JSON-LD format, helping search engines understand your content better and potentially enabling rich results.
24
+
-**FAQ Parsing**: Automatically parses FAQ sections (if present) and includes them in the structured data for enhanced search visibility.
25
+
-**Customizable Styling**: Includes optional inline CSS to maintain consistent styling for plugin elements across your documentation, aligning with themes like [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
21
26
22
-
## 🛠 Installation
27
+
## 🛠️ Installation
23
28
24
-
Getting started with the MkDocs Ultralytics Plugin is easy! Install it via [pip](https://pypi.org/project/mkdocs-ultralytics-plugin/)with the following command:
29
+
Getting started with the MkDocs Ultralytics Plugin is straightforward. Install it via [pip](https://pypi.org/project/pip/)using the following command:
25
30
26
31
```bash
27
32
pip install mkdocs-ultralytics-plugin
28
33
```
29
34
30
35
## 💻 Usage
31
36
32
-
To enable the plugin in your MkDocs configuration, simply add it under the `plugins` section in your `mkdocs.yml` file:
37
+
To activate the plugin within your MkDocs project, add it to the `plugins` section of your `mkdocs.yml` configuration file:
33
38
34
39
```yaml
35
40
plugins:
36
-
- mkdocstrings
37
-
- search
38
-
- ultralytics
41
+
- mkdocstrings# Example of another plugin
42
+
- search# Example of another plugin
43
+
- ultralytics# Add the Ultralytics plugin here
39
44
```
40
45
41
-
## ⚙️ Plugin Arguments
46
+
## ⚙️ Configuration Arguments
42
47
43
-
The plugin supports several configuration arguments to tailor its behavior to your needs:
48
+
The plugin offers several configuration arguments to customize its behavior according to your project's requirements:
44
49
45
-
- `verbose`: Toggles verbose output. Useful for debugging. (default: `True`)
default_image: "https://www.ultralytics.com/images/social.png" # Example default image
72
+
default_author: "git@ultralytics.com" # Example default author
68
73
add_desc: True
69
74
add_image: True
70
75
add_keywords: True
71
76
add_share_buttons: True
72
-
add_authors: False
73
-
add_json_ld: False
77
+
add_authors: False # Disabled by default
78
+
add_json_ld: False # Disabled by default
74
79
add_css: True
75
80
```
76
81
77
-
## 🧩 How it works
82
+
## 🧩 How It Works
78
83
79
-
Here's a breakdown of the plugin's inner workings:
84
+
Here’s a brief overview of the plugin's core functionalities:
80
85
81
-
### Meta Description
86
+
### Meta Description Generation
82
87
83
-
When `add_desc` is on, the plugin plucks the first paragraph from your Markdown and turns it into a `<meta name="description">` tag within the `<head>` of your page.
88
+
When `add_desc` is enabled, the plugin extracts the first paragraph from your Markdown content and uses it to generate a `<meta name="description">` tag within the `<head>` section of the corresponding HTML page. This helps search engines and users understand the page's content at a glance.
84
89
85
-
### Meta Image
90
+
### Meta Image Tagging
86
91
87
-
Enabled by `add_image`, the first available image in the Markdown is assigned as `<meta property="og:image">` and `<meta property="twitter:image">` tags. If no image is detected, `default_image` steps in.
92
+
If `add_image` is active, the plugin identifies the first image referenced in the Markdown source. This image URL is then used to populate the `<meta property="og:image">` and `<meta property="twitter:image">` tags. If no image is detected on the page, the URL provided in `default_image` (if set) is used as a fallback.
88
93
89
-
### Meta Keywords
94
+
### Meta Keyword Integration
90
95
91
-
Manually specify meta keywords in the Markdown front matter to inject a `<meta name="keywords">` tag into the `<head>` of your page.
96
+
By defining keywords in the Markdown front matter (e.g., `keywords: machine learning, computer vision, mkdocs`), and with `add_keywords` enabled, the plugin injects a corresponding `<meta name="keywords">` tag into the page's `<head>`.
92
97
93
-
### Share Buttons
98
+
### Social Share Buttons
94
99
95
-
Engage `add_share_buttons`, and voila! Twitter and LinkedIn sharing buttons appear, inviting users to spread the word about your content.
100
+
Activating `add_share_buttons` automatically appends pre-styled Twitter and LinkedIn sharing buttons to the bottom of your main content area, making it easy for readers to share your documentation.
96
101
97
-
### Git Dates and Authors
102
+
### Git Information Display
98
103
99
-
With `add_dates` and `add_authors`, the plugin fetches and flaunts the git commit timestamp and author names at the bottom of your page, keeping readers informed.
104
+
When `add_authors` is enabled, the plugin leverages Git history to retrieve the commit timestamp and author(s) for each page. This information is then displayed at the bottom of the page, providing context on when the content was last updated and by whom.
100
105
101
106
## 💡 Plugin Code Insight
102
107
103
-
The `MetaPlugin` class within `plugin.py` is the heart of the plugin, orchestrating the metadata and feature insertions:
108
+
The core logic resides within the `MetaPlugin` class in `plugin.py`. This class hooks into the MkDocs build process to modify page content and metadata.
104
109
105
110
```python
106
-
# Our MkDocs plugin inherits features from the BasePlugin available in mkdocs
111
+
# Import the base class for MkDocs plugins
107
112
from mkdocs.plugins import BasePlugin
108
113
109
114
110
-
# The MetaPlugin class holds the core functionality
115
+
# Define the MetaPlugin class inheriting from BasePlugin
111
116
class MetaPlugin(BasePlugin):
112
-
# Acts on the page content to generate meta tags
117
+
# This method runs after the Markdown is converted to HTML,
118
+
# but before the template is rendered.
119
+
# It's used here primarily to extract information like the first paragraph or image.
# ... (omitted code handling meta description and image generation)
115
-
# Comments could further explain code (but are omitted for brevity)
116
-
return content
117
-
118
-
# Alters the final page output to include the new meta tags
121
+
# Logic to find the first paragraph for meta description
122
+
# Logic to find the first image for meta image tags
123
+
# ... (details omitted for brevity)
124
+
# The modified or extracted data is often stored for later use.
125
+
return content # Return the original content, as modifications happen later
126
+
127
+
# This method runs after the page template has been rendered.
128
+
# It allows modification of the final HTML output.
119
129
def on_post_page(self, output, page, config):
120
-
# ... (omitted code that injects generated meta tags into the output)
121
-
# Additional comments could describe processing steps
122
-
return output
130
+
# Logic to inject generated meta tags (description, image, keywords) into <head>
131
+
# Logic to add share buttons HTML to the end of the content area
132
+
# Logic to add author/date footer HTML
133
+
# Logic to add JSON-LD script tag to <head>
134
+
# Logic to add inline CSS if enabled
135
+
# ... (details omitted for brevity)
136
+
return output # Return the modified HTML output
123
137
```
124
138
139
+
This structure allows the plugin to analyze content and then inject the necessary HTML elements and metadata into the final output effectively. Check the source code for the full implementation details.
140
+
125
141
## 🤝 Contribute
126
142
127
-
Join in on the collaboration! 🤗 The success of Ultralytics' open-source initiatives springs from the vibrant contributions of our community. Whether you're fixing bugs, adding features, warming up our discussions, or sharing your Ultralytics project tale, [check out](https://docs.ultralytics.com/help/contributing/) how you can be part of the journey. Filling out our [survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey) is another great way to share your feedback. We are deeply thankful 🙇♂️ for each contributor's time and efforts!
143
+
Collaboration fuels innovation! 🤗 The success of Ultralytics' open-source projects, including this plugin, thrives on community contributions. We welcome your involvement, whether it's fixing bugs, proposing new features, improving documentation, engaging in discussions, or sharing how you use Ultralytics tools.
128
144
129
-
<!-- A visual tribute to our contributors! -->
145
+
Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributing/) for more details on how you can make a difference. Filling out our short [Survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey) also provides valuable feedback. We sincerely appreciate 🙇♂️ every contribution!
Ultralytics projects come with two licensing flavors:
151
+
Ultralytics provides two licensing options to accommodate different use cases:
137
152
138
-
- **AGPL-3.0 License**: This license fosters open collaboration and knowledge sharing, making it a perfect match for students and hobbyists. For specifics, check the [LICENSE](https://github.com/ultralytics/ultralytics/blob/main/LICENSE) file.
139
-
- **Enterprise License**: When it comes to commercial endeavors, this license gets things rolling by allowing Ultralytics software and AI models to be woven into your business offerings without the AGPL-3.0's open-source constraints. For commercial integrations, please explore our [Ultralytics Licensing](https://www.ultralytics.com/license) options.
153
+
- **AGPL-3.0 License**: Ideal for students, researchers, and enthusiasts, this [OSI-approved](https://opensource.org/license/agpl-v3) license promotes open collaboration and knowledge sharing. See the [LICENSE](https://github.com/ultralytics/mkdocs/blob/main/LICENSE) file for details.
154
+
- **Enterprise License**: Designed for commercial applications, this license allows seamless integration of Ultralytics software and AI models into commercial products and services, bypassing the open-source requirements of AGPL-3.0. If your project requires an Enterprise License, please visit [Ultralytics Licensing](https://www.ultralytics.com/license).
140
155
141
156
## ✉️ Connect with Us
142
157
143
-
Have you stumbled upon a glitch, or do you have a splendid feature idea? Pop over to [GitHub Issues](https://github.com/ultralytics/mkdocs/issues) to drop us a line! Also, join our [Discord](https://discord.com/invite/ultralytics) and [Reddit](https://www.reddit.com/r/ultralytics/) for buzzing discussions, insights, and tips around our shared ML journeys.
158
+
Encountered a bug or have an idea for a new feature? Please visit [GitHub Issues](https://github.com/ultralytics/mkdocs/issues) to report problems or suggest enhancements. For broader discussions, questions, and community support related to Ultralytics projects, join our vibrant [Discord](https://discord.com/invite/ultralytics) server and check out the [Ultralytics Reddit](https://www.reddit.com/r/ultralytics/?rdt=34950).
0 commit comments