# MkDocs - Open in a new tab plugin
<p align="center">
<a href="https://hits.seeyoufarm.com"><img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FJakubAndrysek%2Fmkdocs-open-in-new-tab&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=true"/></a>
<img src="https://img.shields.io/github/license/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square">
<img src="https://img.shields.io/github/v/release/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square">
<img src="https://img.shields.io/github/stars/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square">
<img src="https://img.shields.io/github/forks/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square">
<img src="https://img.shields.io/github/issues/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square">
<img src="https://static.pepy.tech/personalized-badge/mkdocs-open-in-new-tab?period=month&units=international_system&left_color=black&right_color=orange&left_text=Downloads">
</p>
This plugin adds JS code to open outgoing links and PDFs in a new tab.
The automatic opening of links in a new tab is a common feature of modern websites. It is also a good practice for accessibility. However, it is not a default behavior of Markdown. This plugin adds a JavaScript code to your website that opens external links and PDFs in a new tab.
Look at the [demo](https://newtab.kubaandrysek.cz/).
## Installation
Install the plugin using pip from [PyPI](https://pypi.org/project/mkdocs-open-in-new-tab/):
```bash
pip install mkdocs-open-in-new-tab
```
## Usage
Add the plugin to your `mkdocs.yml`:
```yaml
plugins:
- search
- open-in-new-tab
```
## Configuration
The plugin supports the following configuration option:
- `add_icon:` (default: false)
- If set to true, the plugin will add an icon next to external links.
## Testing
Link to [Google](https://google.com) and [GitHub](https://github.com).
Both should links should open in a new tab.
Relative link to [Relative link](./docs/RelativeLink.md) should open in the same tab.
Sample PDF link to [PDF](./docs/assets/sample.pdf) should open in a new tab (pdf from [here](https://www.africau.edu/images/default/sample.pdf)).
# How does it work?
The plugin adds a JavaScript code to your website that opens external links and PDFs in a new tab. Injection of the code is done using the `on_page_context` hook. The code is injected into the `<head>` section of the page as a `<script>` dependency of the `open_in_new_tab.js` file. The code is automatically added to all pages of your website.
The function `external_new_window` checks if the link is external using the `hostname` property of the `a` element. If the link is external, the `target` attribute is set to `_blank` and the `rel` attribute is set to `noopener`. The `noopener` attribute is used to prevent the new tab from accessing the `window.opener` property and ensures that the original page will not be able to access the new tab.
The same way is used to open PDF links in a new tab.
<details><summary>Show source code</summary>
<p>
Look at this source <a href="https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/blob/main/open_in_new_tab/js/open_in_new_tab.js">open_in_new_tab.js</a>:
```js
// Description: Open external links in a new tab and PDF links in a new tab
// Based on: https://jekyllcodex.org/without-plugin/new-window-fix/
// Open external links in a new window
function external_new_window() {
for(let c = document.getElementsByTagName("a"), a = 0; a < c.length; a++) {
let b = c[a];
if(b.getAttribute("href") && b.host !== location.host) {
b.target = "_blank";
b.rel = "noopener";
}
}
}
// Open PDF links in a new window
function pdf_new_window() {
if (!document.getElementsByTagName) {
return false;
}
const extensions = ['.pdf', '.doc', '.docx', '.json', '.xls', '.xlsx', '.ppt', '.pptx', '.zip', '.rar', '.tar', '.gz', '.7z', '.bz2', '.xz', '.tgz', '.tar.gz'];
let links = document.getElementsByTagName("a");
for (let eleLink = 0; eleLink < links.length; eleLink++) {
let href = links[eleLink].href.toLowerCase(); // Convert href to lowercase for case-insensitive matching
if (extensions.some(ext => href.endsWith(ext))) {
links[eleLink].onclick = function() {
window.open(this.href);
return false;
}
}
}
}
function apply_rules() {
external_new_window();
pdf_new_window();
}
if (typeof document$ !== "undefined") {
// Compatibility with mkdocs-material's instant loading feature
document$.subscribe(function() {
apply_rules();
});
} else {
// For browsers without mkdocs-material's instant loading feature
document.addEventListener("DOMContentLoaded", function() {
apply_rules();
});
}
```
`open_in_new_tab.css` (added when add_icon: true)
```css
/*
* Materialize links that open in a new window with a right-up arrow icon
* Author: @ebouchut (https://github.com/ebouchut)
* https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/4
*/
a[target="_blank"]::after {
content: "↗";
display: inline-block;
margin-left: 0.2em;
width: 1em;
height: 1em;
}
```
</p>
</details>
## License
This project is licensed under the terms of the MIT license.
Raw data
{
"_id": null,
"home_page": "https://github.com/JakubAndrysek/mkdocs-open-in-new-tab",
"name": "mkdocs-open-in-new-tab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mkdocs plugin, open in new tab, mkdocs, plugin, relative links, links",
"author": "Jakub Andr\u00fdsek",
"author_email": "email@kubaandrysek.cz",
"download_url": "https://files.pythonhosted.org/packages/0a/0e/f72a506a21bdb27b807124e00c688226848a388d1fd3980b80ae3cc27203/mkdocs_open_in_new_tab-1.0.8.tar.gz",
"platform": null,
"description": "# MkDocs - Open in a new tab plugin\n\n<p align=\"center\">\n<a href=\"https://hits.seeyoufarm.com\"><img src=\"https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FJakubAndrysek%2Fmkdocs-open-in-new-tab&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=true\"/></a>\n<img src=\"https://img.shields.io/github/license/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square\">\n<img src=\"https://img.shields.io/github/v/release/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square\">\n<img src=\"https://img.shields.io/github/stars/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square\">\n<img src=\"https://img.shields.io/github/forks/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square\">\n<img src=\"https://img.shields.io/github/issues/JakubAndrysek/mkdocs-open-in-new-tab?style=flat-square\">\n<img src=\"https://static.pepy.tech/personalized-badge/mkdocs-open-in-new-tab?period=month&units=international_system&left_color=black&right_color=orange&left_text=Downloads\">\n</p>\n\nThis plugin adds JS code to open outgoing links and PDFs in a new tab.\n\nThe automatic opening of links in a new tab is a common feature of modern websites. It is also a good practice for accessibility. However, it is not a default behavior of Markdown. This plugin adds a JavaScript code to your website that opens external links and PDFs in a new tab.\n\nLook at the [demo](https://newtab.kubaandrysek.cz/).\n\n## Installation\n\nInstall the plugin using pip from [PyPI](https://pypi.org/project/mkdocs-open-in-new-tab/):\n\n```bash\npip install mkdocs-open-in-new-tab\n```\n\n## Usage\n\nAdd the plugin to your `mkdocs.yml`:\n\n```yaml\nplugins:\n - search\n - open-in-new-tab\n```\n\n## Configuration\n\nThe plugin supports the following configuration option:\n\n- `add_icon:` (default: false)\n - If set to true, the plugin will add an icon next to external links.\n\n\n## Testing\nLink to [Google](https://google.com) and [GitHub](https://github.com).\nBoth should links should open in a new tab.\n\nRelative link to [Relative link](./docs/RelativeLink.md) should open in the same tab.\n\nSample PDF link to [PDF](./docs/assets/sample.pdf) should open in a new tab (pdf from [here](https://www.africau.edu/images/default/sample.pdf)).\n\n\n# How does it work?\nThe plugin adds a JavaScript code to your website that opens external links and PDFs in a new tab. Injection of the code is done using the `on_page_context` hook. The code is injected into the `<head>` section of the page as a `<script>` dependency of the `open_in_new_tab.js` file. The code is automatically added to all pages of your website.\n\n\nThe function `external_new_window` checks if the link is external using the `hostname` property of the `a` element. If the link is external, the `target` attribute is set to `_blank` and the `rel` attribute is set to `noopener`. The `noopener` attribute is used to prevent the new tab from accessing the `window.opener` property and ensures that the original page will not be able to access the new tab.\n\nThe same way is used to open PDF links in a new tab.\n\n\n\n<details><summary>Show source code</summary>\n<p>\n\nLook at this source <a href=\"https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/blob/main/open_in_new_tab/js/open_in_new_tab.js\">open_in_new_tab.js</a>:\n\n```js\n// Description: Open external links in a new tab and PDF links in a new tab\n// Based on: https://jekyllcodex.org/without-plugin/new-window-fix/\n\n// Open external links in a new window\nfunction external_new_window() {\n for(let c = document.getElementsByTagName(\"a\"), a = 0; a < c.length; a++) {\n let b = c[a];\n if(b.getAttribute(\"href\") && b.host !== location.host) {\n b.target = \"_blank\";\n b.rel = \"noopener\";\n }\n }\n}\n\n// Open PDF links in a new window\nfunction pdf_new_window() {\n if (!document.getElementsByTagName) {\n return false;\n }\n\n const extensions = ['.pdf', '.doc', '.docx', '.json', '.xls', '.xlsx', '.ppt', '.pptx', '.zip', '.rar', '.tar', '.gz', '.7z', '.bz2', '.xz', '.tgz', '.tar.gz'];\n let links = document.getElementsByTagName(\"a\");\n\n for (let eleLink = 0; eleLink < links.length; eleLink++) {\n let href = links[eleLink].href.toLowerCase(); // Convert href to lowercase for case-insensitive matching\n\n if (extensions.some(ext => href.endsWith(ext))) {\n links[eleLink].onclick = function() {\n window.open(this.href);\n return false;\n }\n }\n }\n}\n\nfunction apply_rules() {\n external_new_window();\n pdf_new_window();\n}\n\nif (typeof document$ !== \"undefined\") {\n // Compatibility with mkdocs-material's instant loading feature\n document$.subscribe(function() {\n apply_rules();\n });\n} else {\n // For browsers without mkdocs-material's instant loading feature\n document.addEventListener(\"DOMContentLoaded\", function() {\n apply_rules();\n });\n}\n\n```\n\n`open_in_new_tab.css` (added when add_icon: true)\n\n```css\n/*\n * Materialize links that open in a new window with a right-up arrow icon\n * Author: @ebouchut (https://github.com/ebouchut)\n * https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/4\n */\n a[target=\"_blank\"]::after {\n content: \"\u2197\";\n display: inline-block;\n margin-left: 0.2em;\n width: 1em;\n height: 1em;\n}\n```\n\n</p>\n</details>\n\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin to open outgoing links and PDFs in new tab.",
"version": "1.0.8",
"project_urls": {
"Homepage": "https://github.com/JakubAndrysek/mkdocs-open-in-new-tab"
},
"split_keywords": [
"mkdocs plugin",
" open in new tab",
" mkdocs",
" plugin",
" relative links",
" links"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "219444f3c868495481c868d08eea065c82803f1affd8553d3383b782f497613c",
"md5": "fe0562964497364798570d4734a264c8",
"sha256": "051d767a4467b12d89827e1fea0ec660b05b027c726317fe4fceee5456e36ad2"
},
"downloads": -1,
"filename": "mkdocs_open_in_new_tab-1.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe0562964497364798570d4734a264c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7717,
"upload_time": "2024-11-18T13:15:12",
"upload_time_iso_8601": "2024-11-18T13:15:12.286067Z",
"url": "https://files.pythonhosted.org/packages/21/94/44f3c868495481c868d08eea065c82803f1affd8553d3383b782f497613c/mkdocs_open_in_new_tab-1.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0a0ef72a506a21bdb27b807124e00c688226848a388d1fd3980b80ae3cc27203",
"md5": "966277137b8989a0e0203a6d605e6e92",
"sha256": "3e0dad08cc9938b0b13097be8e0aa435919de1eeb2d1a648e66b5dee8d57e048"
},
"downloads": -1,
"filename": "mkdocs_open_in_new_tab-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "966277137b8989a0e0203a6d605e6e92",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5791,
"upload_time": "2024-11-18T13:15:13",
"upload_time_iso_8601": "2024-11-18T13:15:13.977968Z",
"url": "https://files.pythonhosted.org/packages/0a/0e/f72a506a21bdb27b807124e00c688226848a388d1fd3980b80ae3cc27203/mkdocs_open_in_new_tab-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-18 13:15:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JakubAndrysek",
"github_project": "mkdocs-open-in-new-tab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mkdocs-open-in-new-tab"
}
JSON
