gnoxnahte_obsidian-auto-embed/README.md

132 lines
8.4 KiB
Markdown
Raw Permalink Normal View History

2024-09-05 15:27:50 +00:00
[![GitHub manifest version](https://img.shields.io/github/manifest-json/v/gnoxnahte/obsidian-auto-embed)](../../releases)
[![GitHub last commit](https://img.shields.io/github/last-commit/gnoxnahte/obsidian-auto-embed)](../../commits/main/)
[![GitHub Open Issues](https://img.shields.io/github/issues/gnoxnahte/obsidian-auto-embed)](../../issues)
[![GitHub Closed Issues](https://img.shields.io/github/issues-closed/gnoxnahte/obsidian-auto-embed)](../../issues?q=is%3Aissue+is%3Aclosed)
[![GitHub License](https://img.shields.io/github/license/gnoxnahte/obsidian-auto-embed)](/LICENSE)
2024-09-08 03:12:03 +00:00
[![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fobsidianmd%2Fobsidian-releases%2Fmaster%2Fcommunity-plugin-stats.json&query=%24%5B%22auto-embed%22%5D.downloads&logo=obsidian&logoColor=a88bfa&label=downloads&color=a88bfa)](https://obsidian.md/plugins?id=auto-embed)
2024-09-26 04:01:15 +00:00
# obsidian-auto-embed
2024-03-21 15:36:36 +00:00
[Obsidian](https://obsidian.md/) plugin to help embed links automatically instead of using iframes
2024-03-06 07:57:25 +00:00
2024-03-21 14:36:32 +00:00
## Getting Started
2024-04-05 14:55:56 +00:00
Assuming you have [Obsidian](https://obsidian.md/) downloaded,
Download the plugin: https://obsidian.md/plugins?id=auto-embed
2024-03-29 10:18:40 +00:00
2024-03-21 14:36:32 +00:00
### Embedding links
1. Paste a link
2. Select "Create Embed"
3. (Optional) Add [Options](#custom-options)
4. Done! Wait for the embed to load
2024-09-26 04:01:15 +00:00
https://github.com/user-attachments/assets/def3599a-bac6-4517-83f3-96fc6ba5a815
2024-03-21 14:36:32 +00:00
Uses the same syntax as Obsidian - [Embed Web pages](https://help.obsidian.md/Editing+and+formatting/Embed+web+pages). Syntax: `![options](link)`
2024-03-06 07:57:25 +00:00
2024-03-21 14:36:32 +00:00
## Features
Auto embeds websites like: [Imgur](https://imgur.com/), [CodePen](https://codepen.io/), [Steam](https://store.steampowered.com/). Full list of [supported websites](#supported-websites)
2024-03-10 12:53:54 +00:00
2024-03-06 07:57:25 +00:00
### Supported websites:
#### Social Media:
- [X](https://x.com) *
- [Reddit](https://www.reddit.com/)
- [TikTok](https://www.tiktok.com/)
#### Sound/Music:
- [Spotify](https://open.spotify.com/) *
- [SoundCloud](https://soundcloud.com/)
#### Others:
2024-03-21 14:36:32 +00:00
- [CodePen](https://codepen.io/)
- [Steam](https://store.steampowered.com/)
- [Imgur](https://imgur.com/)
- [Notion](https://www.notion.so/) *
2024-03-21 14:36:32 +00:00
> [!WARNING]
> Websites with `*` means that it has some sort of limitation/note. See [Current Limitations & Known Bugs](#current-limitations--known-bugs) for more info
For unsupported websites, the plugin will embed the whole website and not modify it.
For a list with examples of how the websites look like [Supported Websites List](SupportedWebsiteList.md).
2024-03-21 14:36:32 +00:00
## Custom Options
How to add options:
2024-04-05 14:55:56 +00:00
- In between the square brackets - `![add options here](https://example.com)`
2024-03-21 14:36:32 +00:00
- If you aren't sure which options are available, refer to the table below
### All options:
| Option | Description | Example Markdown |
|---|---|---|
2024-03-29 09:42:24 +00:00
|noembed|Disables embedding for this link. If possible, try using `[](link)` instead. Same syntax, just without '!'|`![noembed](https://example.com)`
|w:`value` / width:`value`|Sets embed's width|`![w:100%](https://example.com)`
|h:`value` / height:`value`|Sets embed's height |`![h:500px](https://example.com)`
2024-03-21 14:36:32 +00:00
<!---
TODO: Dark mode
TODO: Find out how to format size. the separator between width and height is "x". Conflicts with "px"
2024-03-21 14:36:32 +00:00
|size: `value`x`value`|Sets both embed's width and height. Uses [CSS Units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths)|`[size:100%x300px](example.com)`
--->
Uses [CSS Units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths) where applicable.
2024-04-05 14:55:56 +00:00
## Custom styles
TODO: Add a table that lists all the CSS classes users can override.
2024-03-21 14:36:32 +00:00
## How the plugin works
A brief overview with some steps on how the plugin works. *Not required to use the plugin*, just for those who are curious. Certain steps vary depending on whether you're in **Reading View** or **Live Preview**. However, the plugin doesn't have any impact when you're in source mode.
1. Search where in the document the syntax is found.
- In **Reading View**: <br>
Searches for the `<img>` tag that's generated by Obsidian when you use this format: `![](link)`
- In **Live Preview**: <br>
Searches for `![](link)` and gets the [options](#custom-options) and URL from it.
2. Get the URL from it, and convert it to the embed equivalent. Usually adds `/embed/` somewhere in the url. Results in the same website but focused only on the content. No headers, footer, etc
2024-03-21 15:36:36 +00:00
- Example: <br>https://codepen.io/jh3y/pen/LYNZwGm converts to https://codepen.io/jh3y/embed/LYNZwGm?default-tab=result&editable=true
3. Replace those tags with `<iframe>` and apply options (width, height, dark mode, etc)
2024-03-21 15:36:36 +00:00
4. Some websites like Twitter, Reddit or Imgur, will send a resize message. The plugin uses the info to resize the embed.
2024-03-21 14:36:32 +00:00
## Roadmap
- [ ] Add support for other websites (If you want other websites, [create an issue](https://github.com/GnoxNahte/obsidian-auto-embed/issues) or [submit a Google Form](https://forms.gle/xtuv4FVCKZ2tg9zK9) if u aren't comfortable with GitHub)
2024-03-10 12:53:54 +00:00
- [ ] Google Maps
- [ ] Google Calendar
- [ ] Other websites. [Iframely](https://iframely.com/domains) has a list of websites that can be embedded.
- [ ] Add preview websites when hovering a link and holding `Ctrl` for websites that aren't embedded using the syntax.
2024-03-06 07:57:25 +00:00
- [ ] Add tests
2024-03-21 14:36:32 +00:00
- [ ] Updated README.md
2024-03-29 09:42:24 +00:00
- [ ] Improve readability. Open to suggestions, especially if something isn't clear.
- [ ] Add images/gifs to show examples
2024-03-06 07:57:25 +00:00
- [ ] Add installation instructions
Submit any features you want here: https://forms.gle/xtuv4FVCKZ2tg9zK9
2024-03-10 12:53:54 +00:00
### Current Limitations & Known Bugs
- General
- **Live Preview**:
- The cursor location doesn't match with Obsidian's [Embed Web pages](https://help.obsidian.md/Editing+and+formatting/Embed+web+pages). Still trying to fix it.
- Rarely happens but sometimes it glitches out and doesn't let you edit. When it does that, either restart the app or switch to [Source mode](https://help.obsidian.md/Editing+and+formatting/Edit+and+preview+Markdown#Source+mode).
- Website specific
- **Spotify**: Only able to play 30 seconds of a song. Spotify only allows when the user is logged in to the browser, which isn't possible in Obsidian.
- **Reddit**: Share link (link with `/s/` instead of `/comments/` in the URL) isn't supported. As a workaround, open the link in a browser and Reddit should redirect it to the `/comments/` link which is supported.
- **Notion**: The notion note needs to be a [published website](https://www.notion.so/help/public-pages-and-web-publishing). Also, the plugin isn't doing anything special for Notion. Unlike other websites, it's just using the raw link as an iframe.
2024-04-05 14:55:56 +00:00
- **Twitter & YouTube**: Since [Obsidian supports it](https://help.obsidian.md/Editing+and+formatting/Embed+web+pages), I won't interfere with it. However, it means [options](#custom-options) isn't supported. I might be able to replace Obsidian's embeds with mine, but [options](#custom-options) will only work in *Live Preview*, but not *Reading Mode*. This makes an inconsistent user experience but if you want this feature, contact me / create a pull request.
- **Twitter / X**: Obsidian supports https://twitter.com but not https://x.com. This plugin just helps to embed X. If you replace Twitter with x, or vice versa, it'll lead to the same tweet/post. Usually when copying from the mobile app, it's X. When copying from the web, it's Twitter.
Please [send any issues](https://github.com/GnoxNahte/obsidian-auto-embed/issues) you found!
2024-03-10 12:53:54 +00:00
## Frequently asked questions
### The embed isn't appearing
1. Have you [enabled the plugin](https://help.obsidian.md/Extending+Obsidian/Community+plugins#Enable+a+community+plugin)?
2024-03-21 14:36:32 +00:00
2. Are you following this syntax? `![](link)`<br>
2024-04-05 14:55:56 +00:00
For example: `![](https://example.com)`
3. If it still doesn't work, try contacting me or create an issue.
2024-03-10 12:53:54 +00:00
## Contact Me
2024-03-21 14:36:32 +00:00
I've just started Obsidian and this is my first plugin.<br>
If you have any questions, feature requests, bugs or anything related to the plugin, feel free to [create an issue](https://github.com/GnoxNahte/obsidian-auto-embed/issues/new) or [submit a Google Form](https://forms.gle/xtuv4FVCKZ2tg9zK9).
2024-03-10 12:53:54 +00:00
Alternatively, you can [email](mailto:gnoxnahte.dev@gmail.com) me too.
2024-03-06 07:57:25 +00:00
If this plugin helped you and want to support its development, please consider supporting me at [Ko-fi](https://ko-fi.com/gnoxnahtedev)
## Credits
- Inspired by Sam Warnick's [Simple Embed](https://github.com/samwarnick/obsidian-simple-embeds). It was archived so I made my own plugin. Changed a lot of things from it though.