# 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
```
## 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
// Source: 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.hostname !== location.hostname) {
b.target = "_blank";
b.rel = "noopener";
}
}
}
//open PDF links in a new window
function pdf_new_window ()
{
if (!document.getElementsByTagName) {
return false;
}
let links = document.getElementsByTagName("a");
for (let eleLink=0; eleLink < links.length; eleLink ++) {
if ((links[eleLink].href.indexOf('.pdf') !== -1)||(links[eleLink].href.indexOf('.doc') !== -1)||(links[eleLink].href.indexOf('.docx') !== -1)) {
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
// based on code from https://github.com/timvink/mkdocs-charts-plugin
// Copyright (c) 2021 Tim Vink - MIT License
// fixes [Issue #2](https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/2)
document$.subscribe(function() {
apply_rules();
})
}
```
</p>
</details>
<!-- ## Known issues
This extension does not work with mkdocs-material [navigation.instant](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading). JS could not be loaded when the page is loaded instantly. If you know how to fix it, please let me know. Issue is [here](https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/2). -->
## 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": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"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/20/d7/1cfc6341e606493d476c2821ad151f77db6b10e89c60878e344a8af87a82/mkdocs-open-in-new-tab-1.0.3.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\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// Source: 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.hostname !== location.hostname) {\n b.target = \"_blank\";\n b.rel = \"noopener\";\n }\n }\n}\n//open PDF links in a new window\nfunction pdf_new_window ()\n{\n if (!document.getElementsByTagName) {\n return false;\n }\n let links = document.getElementsByTagName(\"a\");\n for (let eleLink=0; eleLink < links.length; eleLink ++) {\n if ((links[eleLink].href.indexOf('.pdf') !== -1)||(links[eleLink].href.indexOf('.doc') !== -1)||(links[eleLink].href.indexOf('.docx') !== -1)) {\n links[eleLink].onclick =\n 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 // based on code from https://github.com/timvink/mkdocs-charts-plugin\n // Copyright (c) 2021 Tim Vink - MIT License\n // fixes [Issue #2](https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/2)\n document$.subscribe(function() {\n apply_rules();\n })\n}\n```\n</p>\n</details>\n\n<!-- ## Known issues\nThis extension does not work with mkdocs-material [navigation.instant](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading). JS could not be loaded when the page is loaded instantly. If you know how to fix it, please let me know. Issue is [here](https://github.com/JakubAndrysek/mkdocs-open-in-new-tab/issues/2). -->\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.3",
"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": "69a5265c57ed951caa0c09d776d82363e840b8d5a04157a8240f8b2f590ec847",
"md5": "4903641b290c301592cd6eaeef54a87f",
"sha256": "e2ddfa02f53d7c16d8430f5c0b3d98c4b98c82e1b8aa6fbdc91c78e89bbeb5f1"
},
"downloads": -1,
"filename": "mkdocs_open_in_new_tab-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4903641b290c301592cd6eaeef54a87f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6736,
"upload_time": "2023-10-24T19:54:10",
"upload_time_iso_8601": "2023-10-24T19:54:10.518427Z",
"url": "https://files.pythonhosted.org/packages/69/a5/265c57ed951caa0c09d776d82363e840b8d5a04157a8240f8b2f590ec847/mkdocs_open_in_new_tab-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "20d71cfc6341e606493d476c2821ad151f77db6b10e89c60878e344a8af87a82",
"md5": "cc4e3a2a27b0b936991783180c403ede",
"sha256": "a40231901b12f01a1d4b798112712d475741356e550d8f3adf3ca23e332a7d2c"
},
"downloads": -1,
"filename": "mkdocs-open-in-new-tab-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "cc4e3a2a27b0b936991783180c403ede",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4879,
"upload_time": "2023-10-24T19:54:12",
"upload_time_iso_8601": "2023-10-24T19:54:12.727609Z",
"url": "https://files.pythonhosted.org/packages/20/d7/1cfc6341e606493d476c2821ad151f77db6b10e89c60878e344a8af87a82/mkdocs-open-in-new-tab-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-24 19:54:12",
"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
