GitHub Pages is a great way to host some of your content online. All you need to do is to write some markdown files and tell GitHub to create it as a page.
The problem is that you can't just add some HTML into your markdown to - for example - embed a YouTube video. It does work if all you include is the YouTube iframe, but when you work with professional markdown repos, this will be flagged up as an error or security problem.
A workaround that many people use is to embed a linked preview of the video:
If your YouTube URL is https://www.youtube.com/watch?v=JLMbpiywVxQ the important part is the ID after the v=, in this case JLMbpiywVxQ.
You can then use the following markdown to embed a link to the video with a preview image of it. YouTube automatically creates these preview images.
[![Final video of fixing issues in your code in VS Code]
(https://img.youtube.com/vi/JLMbpiywVxQ/maxresdefault.jpg)]
(https://www.youtube.com/watch?v=JLMbpiywVxQ)
If, however, you want to embed the video in markdown files, you need to do a bit more.
- Go to the root of your GitHub repo with the markdown files and create a folder called
_includes. - In this folder, create a file called
youtube.html. Paste this HTML and CSS and save it.
<div class="embed-container">
<iframe width="640" height="390"
src="https://www.youtube.com/embed/{{ include.id }}"
frameborder="0" allowfullscreen></iframe>
</div>
<style>
.embed-container {
position: relative;
padding-bottom: 56.25%;
height: 0;
overflow: hidden;
max-width: 100%;
}
.embed-container iframe,
.embed-container object,
.embed-container embed {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}
</style>
Now you can embed any YouTube video in your markdown files using the following:
{% include youtube.html id="JLMbpiywVxQ" %}
With the ID being the YouTube ID.
You can see this in action and fork the youtube embed demo repository if you don't want to do it by hand.
Oldest comments (2)
I have to ask about this part:
"The problem is that you can't just add some HTML into your markdown to - for example - embed a YouTube video. It does work if all you include is the YouTube iframe, but when you work with professional markdown repos, this will be flagged up as an error or security problem."
Is that really an issue people run into often? Markdown absolutely allows for any HTML you want, no problem at all. It's entirely possible an organization using MD files in their repo may lint their MD and throw an error on HTML, but that's really going to be pretty rare, is it not?
The idea of linking to the image is a good one, and probably much better for performance, I just worry that the statement above may lead people into thinking it's a bad idea to use ad hoc HTML in MD.
Let me know if I'm crazy (about this anyway ;).
For most use cases that is fine, but, for example in the Microsoft Docs project, we validate the Markdown for possible security issues, which any HTML could become, especially random iframes.