Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/JakubAndrysek/mkdocs-open-in-new-tab
🔮 This plugin adds JS to open outgoing links and PDFs in a new tab.
https://github.com/JakubAndrysek/mkdocs-open-in-new-tab
js markdown mkdocs new-tab new-tab-page plugin pypi-package python
Last synced: 13 days ago
JSON representation
🔮 This plugin adds JS to open outgoing links and PDFs in a new tab.
- Host: GitHub
- URL: https://github.com/JakubAndrysek/mkdocs-open-in-new-tab
- Owner: JakubAndrysek
- License: mit
- Created: 2023-03-26T20:25:28.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-18T14:38:16.000Z (26 days ago)
- Last Synced: 2024-10-18T16:56:58.904Z (26 days ago)
- Topics: js, markdown, mkdocs, new-tab, new-tab-page, plugin, pypi-package, python
- Language: Python
- Homepage: https://newtab.kubaandrysek.cz/
- Size: 648 KB
- Stars: 24
- Watchers: 2
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MkDocs - Open in a new tab plugin
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 `` section of the page as a `` 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.