mkdocs-material
mkdocs-material copied to clipboard
squidfunk
Feature suggestion: Blog
I've been thinking on and off about blog support and think it is ready to be tackled. I want to provide native blog support for Material for MkDocs, which can be used just as easily as the overall project. Before I start implementing, I want to collect some ideas and requirements, so that we can gravitate towards a solution that ticks as many boxes as possible.
Collected ideas
- [ ] Auto-generate blog index page and article pages @squidfunk
- [ ] Auto-generate final URL from date (format can be changed) + title @squidfunk
- [ ] Provide a pagination of the index page @squidfunk
- [ ] Integrate with the built-in tags plugin @squidfunk
- [ ] Allow to provide author information that is automatically rendered @squidfunk
- [ ] Allow to provide static pages alongside articles @squidfunk
- [ ] Allow authors to easily override/extend templates @squidfunk
Feel free to leave further input in the comments
- What navigation and directory structure would you expect from a blog?
- What pages besides the index page do you need? Archive? Tags?
- How would you write a new blog article, i.e., what's the expected DX?
- ... anything else that's on your mind
I'll base this on both my own blog using MkDocs and the one on this repo (The Material for MkDocs site).
Structure
I see a lot of blogging plugins using /:year/:month/:day/:article.md as a base-structure for it to work and I'm not the biggest fan of it.
Preferably would I like a system that allows to define your own sources for articles (possibly with recursive lookup) to pull from, but when a more rigid structure is wanted would I go with /:year/:month/:article.md as not everyone writes 10 articles a day and they usually are unique enough to not have duplicates in any way.
Navigation
One thing I want to suggest is getting rid of the "Previous Page" and "Next page" section for the blog itself and maybe implement a "recommended" part that lists a few articles based on stuff such as tags or date of creation...
I saw a few blogs doing that and I'm a fan of it, especially if it also would have stuff such as preview images or a short description to it.
Example from the Origin Realms blog:
Lightbox/Lightgallery support
Right now I have to use Lightgallery Markdown to have images that expand when you click them. That approach is imo quite hacky and not optimal, so a native support for such a feature (which iirc was quite heavily requested) would be good.
This would be awesome and make the MkDocs system even more powerful. I use MkDocs quite a lot for documentation, but my personal blog is jekyll-based.
The main reason I haven't switched yet is because I want to embed my blog into my personal website, which is more than just a blog. Basically it's this functionality (copied from their docs):
<ul>
{% for post in site.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
That way I can insert, for example, the 3 latest posts somewhere on my homepage. We might be able to do something similar, where you include an HTML file with some jinja2 syntax in your MkDocs site, and have a plugin add the extra context to the mkdocs jinja2 environment. I haven't explored this before, it might already be possible (in which case it isn't obvious enough for users).
Structure
I like jekyll's convention of putting posts in _posts (link to docs), but any directory structure could work. Having a look at jekyll-import might be interesting, and perhaps something similar for mkdocs would help increase adoption.
Using frontmatter for things like tags, categories, permalinks, dates, authors etc works great (docs)
Documentation
There are already quite some mkdocs components out there that combined work well for a blog. Properly documenting and demonstrating the use case for blogging is going to be important for adoption. While we're at it, we can document other use cases as well (technical report, python package, personal site, git-based wiki, etc). And yes, that could be a great way to showcase a whole range most-used of plugins ;)
It would be awesome to have some sort of widget to give readers a visual clue that a new blog entry has been posted. Ideally that could be embedded on third-party sites, although I fully realize that would be out of scope. But I'm thinking about widgets like this, or that.
The ability to broadcast new posts and send notifications via RSS, Twitter, or Slack would be the cherry on top. :)
It would be cool if blog posts, could be liked, or upvoted, to then allow a sorting by most popular.
@LuciferUchiha thanks for your suggestion! Any idea where we could store the data? Remember that Material for MkDocs will generate a static site, so without third-party services, there's no dynamicity.
@squidfunk integration via github issue could be a very easy/viable option. Same emojis can be used.
Things I wanted mkdocs-material-blog to have above the mentioned ones:
- searchable tags
- archive page will all posts chronologically ordered
- support for an author profile that can be linked via meta tags. An author summary is then presented on a post page in the header/footer.
- read time estimation
@squidfunk integration via github issue could be a very easy/viable option. Same emojis can be used.
I feel like using issues for that would be bad, mainly because issues serve different purposes. But perhaps a system similar to what giscus is providing (Maybe even use it for that? Idk) could be an idea. So instead of issues, use discussions for it... But then again, I feel like this could be a bit weird and would also require stuff like managing GitHub OAuth flow and stuff.
Things I wanted mkdocs-material-blog to have above the mentioned ones:
- searchable tags
- archive page will all posts chronologically ordered
- support for an author profile that can be linked via meta tags. An author summary is then presented on a post page in the header/footer.
- read time estimation
Much of what I was going to propose is captured by @hellt
The ability to broadcast new posts and send notifications via RSS, Twitter, or Slack would be the cherry on top. :)
I think this would probably be out-of-scope, but one idea without getting too fancy would be to offer simple "share out" links, similar to this https://fly.io/blog/
I've recently taken some inspiration from this blog: https://fly.io/blog/ .. the one thing I don't like is having to manually page through to discover blog content. IMO this should be configurable whereby the default is to show all post summaries, and if your blog has A LOT of content then flip a bit to render a paginated chronological ordering of post summaries.
Either way, really looking forward to whatever blog support will be included with Material for MkDocs ✌️
For me, some sort of integration with Jupyter notebooks would be useful.
The simplest way to incorporate notebooks would be using nbconvert to convert to markdown and then processing with mkdocs as normal but there might be some added value in e.g. being able to reference individual cells/outputs to include rather than whole notebooks. I'm not sure if that exists elsewhere.
Mathjax is also important for me, but since that works in mkdocs-material I assume that's a given.
@dhirschfeld – all features and specimen that are available in Material for MkDocs will also work with the blog: content tabs, code blocks, code annotations, instant loading, etc.
Another feature that would be handy for blog content is support for draft status in the meta header. Hugo supports this, for example, and will omit rendering the page altogether. This is probably more of a mkdocs plugin than a theme feature though. Similar logic applies for publishDate: only render the page if the current date is equal to or greater than the date shown.
Hello @timvink, thanks for pointing out the https://github.com/greenape/mknotebooks plugin, that looks interesting! I've not yet had time to try that plugin, but I did read its documentation. If I understand it correctly, it seems as though it can execute the Jupyter notebook with a plugin and then display the results of executing the notebook in the rendered version of the site.
Following on from this suggestion, I have a question: Is there a way to run the Python source code in a code block in an interactive fashion directly inside of the web site and then display the result? There are several examples of this type of approach available online but I have not seen something that implements this workflow and integrates into Material for Mkdocs. Here are some references/examples that I have found:
- https://course.spacy.io/en/: Runs the Python source code segments in MyBinder, no export to Binder needed
- https://www.debuggingbook.org/: Also runs the Python source code in MyBinder, requires export of notebook first
- https://jupyterbook.org/interactive/interactive.html: Uses the Thebe package to make interactive source code (reference for details about Thebe and how it integrates into the Jupyter Book project: https://thebe.readthedocs.io/en/latest/index.html)
- https://d2l.ai/index.html: Exports the source code to platforms like Colab and then allows notebook execution
- https://rahul.gopinath.org/post/2021/11/13/regular-grammar-to-regular-expression/: Uses Pyodide to run the Python source code directly in the browser (reference for the Pyodide project: https://pyodide.org/en/stable/index.html)
Thanks in advance for reading this note and, as your schedule permits, suggesting some ways to make the Python source code in a code block. If you can point me in the right direction for a site that has executable code or a package that would be a good place to start, then I would greatly appreciate it! If this feature already exists and I have overlooked it, please let me know as well! Overall, my view is that it would be really awesome if the code blocks in a Material for Mkdocs site were executable!
@timvink @gkapfham could you move this to a separate discussion? It’s not related to the issue at hand but has great value for other users, so a dedicated discussion would be perfect 😊
A few things to bring up having been a huge fan of mkdocs material, and having used jekyll, hugo, ghost, and a plethora of tooling around this.
What navigation and directory structure would you expect from a blog?
I'd like to be able to have a flat doc hiearchy. I think there's a good case for this, so right now I've got my posts as mysite.com/title-name/ without the need to have sub paths. It keeps things nice and simple even if you change structure. Only requirement is that you have unique page titles.
How would you write a new blog article, i.e., what's the expected DX?
I created some Go cli commands so I run: mage post and then select the type of post and it creates a templated markdown file. I mark as a draft or not, and then commit and push. Netlify builds and in roughly 3-4 mins the site is updated. Having some easy tasks to create the right file in the right location help using "archetypes". When I created docs with Mkdocs, I just manually created the files.
Something similar would be good for mkdocs. Allow simple templated types to be called and simple invocation via mkdocs to create. I can post a gif of how this works for me currently if it helps.
What pages besides the index page do you need? Archive? Tags?
In Hugo, I've got a couple types of taxonmy/archive style pages.
- Archive - Filtered to exclude microblog style posts
- Posts - More of a excerpt view of recent content, so microblog + long-form all show up in the same place.
- Tags - Nice to have, primarily to filter RSS output for distribution.
... anything else that's on your mind
Slugs
The slug/naming is critical to allowing folks to migrate to the toolchain. I'd looked at mkdocs before since I really love this material theme for a knowledge base + wanted to blog. As it stands, Hugo provides some nice flexibility in setting the slug scheme, so I can do slug as the primary key, rather than dates being involved. https://github.com/sheldonhull/sheldonhull.hugo/blob/32362c2bd6676910538776118cc4396580a147e2/config.yml#L434
- Note: The front-matter allows override with "slug" so I've had great control regardless of theme migration keeping things from breaking as I typically include the slug explicitly so I have 100% control of my url. For example here I have a title for a Microblog post, but I control the actual page permalink to ensure title can change without breaking in this situation.
Authoring Via Markdown
Source for the blog posts as the "lowest common denominator", is markdown files created via whatever command like mkdocs new post "foo". That said, leveraging GitHub issues for sourcing posts would be pretty cool to consider, but I'd throw out there that anything like this is non-critical to a blogging feature, more like an extension/option that might work for some. I don't consider this a core blogging feature. Also, Forestry might be worth checking out. I've used it for a bit with Hugo and might offer a good partnership if someone really wants a UI integration with this.
RSS
RSS. This feature seems to be a last thought in many of the new "notion to static site" style tooling and other things I've reviewed. It's really important to have control of the RSS produced for blogging if you have any desire to distribute or syndicate your posts, so please consider that a core part of successful blogging implementation. I've had to do a bit of customization in my Hugo blog to get RSS working like I wanted, and breaking subscription links/publishing links is one of those major barriers to migration I've observed.
I'll follow for more detail/discussion threads, as I'm excited to see where this goes. Thank you for such an incredible project! 👍
Thanks to all of you for the great input! It helps a lot to distill a draft for a first iteration 😊
It should also implement the concept of "Series", that is, a set of related articles. An example is https://kubasejdak.com/techniques-of-variadic-templates:
Maybe it is not a visible feature but if something similar to HUGO Shortcodes is implemented but through plugins, new functionalities could be added easily.
Not sure how possible or useful this could be to have, but maybe have some way to send updates for newly made posts?
Like a way to detect a new blog post and in such a case do something like a webhook POST request or similar. Could be useful for people to get informed about new posts outside of methods such as RSS or similar...
I'm stoked for this! Here's what I'd love to see..
- Social share buttons
- The ability to declare author(s) in yaml front matter and have them displayed in the post, similar to how you did it here
- Configurable "previous" and "next" buttons in the footer. It's weird if an article about "dogs" has a next link to an article about finance, just because they're siblings in the
nav.
A sort of way to have multiple blogs under different categories (And maybe even allow to have different default settings per category) would be a nice feature to have.
See https://github.com/liang2kl/mkdocs-blogging-plugin/issues/17 for more details.
What pages besides the index page do you need? Archive? Tags?
I would love to see an option to have multiple article authors with an "Authors overview" (All blog authors with, e.g. social media, website links and a short description) and "John Doe's articles" page (where all articles of that author are listed) and the possibility to assign articles to an author.
What navigation and directory structure would you expect from a blog?
Directory structure using ISO datecode as an option:
/blog/article.md or /blog/yyyymmdd/article.md
On the site it would look like this:
mysite.com/blog/article/ or mysite.com/blog/yyyymmdd/article/
This should be an option that is toggleable in mkdocs.yml ideally when blog is enabled.
What pages besides the index page do you need? Archive? Tags?
As little as possible. The simpler the better is my view. Tags are unnecessary because we have the search function. I would like the blog search results to be segregated from the docs so there isn't noise for the user. The user has to go to the blog site, and then using the search function there is for blog content only. When in the docs side of things, then it only searches the docs. If that makes sense. Tags seem like an old affectation of earlier blogs that no one really should be focusing on in my opinion. People read blogs for updates from a certain site or they find them through search engines online. Whatever optimizes SEO for the blogs is preferred, as is already done with Docs.
I would like to see the ToC from docs disabled by default in blogs so content creators don't need to add the hide header, and navigation sidebar on the left have the blog articles in order from newest to oldest by title, with a cutoff to restrict them to one line. Basically, using blogs would entail using the top bar I think for primary site navigation, similar to how the Material for MkDocs page is already setup.
How would you write a new blog article, i.e., what's the expected DX?
Identical to the docs pages to be quite honest. Blogs to me should be simple to write so content creators don't have to be technically minded, just like the Docs. Look at Medium and other blogsites, highly successful, extremely muted and simple.
...anything else that's on your mind
Thanks for your work on your project, it's helped me create a new proposed documentation site for the MiSTer FPGA project and it's been a lot of fun learning the ins and outs of it all. https://birdybro.github.io/MkDocs_MiSTer/
Edit: The site was approved and is official :D https://mister-devel.github.io/MkDocs_MiSTer/ - thanks again!
That being said, I'm excited about the blogs feature as we want to allow our developers and other contributors an opportunity to submit articles when new updates come out or to show off new features, and would love it all to be on the same site. So this is right up my alley. :)
This will be a great and welcomed addition to the feature set. Thanks for thinking about this and planning to release.
Maybe have a /docs dir for normal docs and a /blog dir for blog posts.
Have a new page added named blog.md similar to how the tags.md page works that will recursively list all posts in the /blog dir.
- To simplify naming, files should be named like
yyyy-mm-dd-article_name.md - To make it more granular timestamp wise, inside each post should allow for a opening section like so:
---
title: Blog Post Title
author:
name: Author Name
link: https://github.com/github_username
date: yyyy-mm-dd hh:mm:ss
categories: [Category, Category]
tags: [tag, tag, tag]
---
this would allow more than one article per day without having to have a ridiculous naming schema.
As far as writing the blog posts, what is provided out of the box already is way more than enough.
This is a great proposal and I believe many people expect this feature! Here are some of my thoughts.
Limited migration effort
By far for tenured users of mkdocs, there might be quite a lot of docs already, some of them can be put in a blog format, so it is very important to ensure that the blog features can empower the existing posts with minimal modifications, say adding some necessary keywords in the header.
Faster deployment and loading speed
A good example is HUGO which is noticeably faster.
A good example
This is a sample framework built with HUGO, the navigations, table of contents and content are mostly similar to mkdocs, but it has a few things I like:
- Posts linked to authors and users can click the author name to see all posts written by the author
- A list view of posts, in fact it is better if the
tagscan be put on top for filtering
Other features mentioned by users above this thread can be addressed with mkdocs plug-ins already, such as:
- like/dislike buttons
- share to social media buttons
- RSS
so I do not think they are dedicated features that will be very beneficial to blogs. Besides, this proposal was brought up five months ago, wonder where it is by far. Again, thank you for the great proposal! @squidfunk
So, just a little heads up: I'm actively working on the blogging feature. I'll need some more time, as it's a pretty big thing to get out the door given the functionality we'd at least need for an MVP, but it'll be worth the wait and just as easy to use as the rest of Material for MkDocs. Furthermore, it will also be possible to build a blog as the main thing, not just as a sidecar, making Material for MkDocs an excellent choice for building a technical blog.
What's time-consuming is all the stuff I need to do besides, like bug fixes, issue triage, etc, so that is the main limiting factor for getting this out the door. I expect many of the requirements that were collected here to be possible, many of them in the first version. Additional functionality will be added gradually, once I could give the blogging feature into your hands!