added example for a stand-alone blog #14
Conversation
|
Perfect, thanks for your work! |
|
Guess this is ready to merge? I will get started on the version showcasing the new authors pages after a show refreshment. |
| plugins: | ||
| - search | ||
| - blog: | ||
| blog_dir: demo |
There was a problem hiding this comment.
Why is the blog contained in the demo directory? IMHO, by definition, a standalone blog lives at the root 😅
There was a problem hiding this comment.
Right, I was going to ask. The demo/ directory is not my invention but something I copied from earlier examples. The way I made sense of it was that it puts README.md in the docs/ folder as the main page for the example, which may be doing things that have nothing to do with the example itself, such as showing bits of the code used. Am just realizing that I have not been consistent in this, either - should have asked about it earlier. Perhaps it made sense for some examples for some specific reason?
There was a problem hiding this comment.
Aaaaah you're absolutey right, forgot about that. Long time since I've created an example. The idea was that the README.md is the main entrypoint that gives the opportunity to explain the example, while the example itself is entirely contained in the demo section. However, I think for the standalone blog, this is questionable. Maybe we should create a recipe for this and make a distinction that recipes don't have a demo section but are themselves runnable and usable from the start. However, let's start here and move stuff out once we created a recipe section.
There was a problem hiding this comment.
There is something of an issue in that MkDocs does not seen to like a README.md to be sitting alongside an index.md. Perhaps that was the original motivation for demo/? I tried to rename index.md to blog.md and point that navigation at that but this causes an exception without further explanation. It also causes an index.md file to be magically created in docs/. Whaa???
There was a problem hiding this comment.
There is, of course, the option to exclude README.md from the build or to move it to an about folder but then it would only show up there on GitHub. Note that all this is a problem only for the stand-alone blog. It is actually here (I think) that the demo/ is needed.
There was a problem hiding this comment.
Hmm, maybe we should really move this into a new section called recipes, cookbooks, or whatever, then. We should definitely keep the demo for examples, but this doesn't really work for the standalone blog. The standalone blog could then also feature a full-blown setup with tags, social cards, etc., basically everything that's in the free version.´, and we could slowly extend it to be a good starter. What do you think?
Maybe we should call it starters, albeit that makes me hungry.
There was a problem hiding this comment.
I just came to realize that everything is about food 😂 Starters, cookbooks, recipes, ...
There was a problem hiding this comment.
feature a full-blown setup with tags, social cards, etc.
That sounds good to me. I will start working on this. TBH, I always felt that the examples are a bit too minimalistic to be of much help to many people but I have no empirical evidence to back that up. Definitely happy to do more to show what amazing things are possible if you put things together in the right way. I keep doing bits of work now and then on the tutorial (recipe, starter, entrée, smorgasbord...) and, no doubt will add more as I pick up useful things while looking at the blog functionality.
One question, though: should we publish the blog-standalone example even if it is a bit odd? We could mention that in the README.
Another one: I have started to write a contributors.md file to document how the examples work. Put a note on us not accepting community contributions just now. If you don't like publishing it (yet) then I could stick the text in to the internal repo for now so we can at least look at it and refine it?
There was a problem hiding this comment.
TBH, I always felt that the examples are a bit too minimalistic to be of much help to many people but I have no empirical evidence to back that up.
Yes, they are very barebone, but don't forget that sometimes people have trouble setting up even the simplest features. In the end, examples help us reduce the number of issues and provide a good starting point for minimal reproductions. They are not intended to be complete, but be as minimalistic as possible.
One question, though: should we publish the blog-standalone example even if it is a bit odd? We could mention that in the README.
Yes, let's keep it as an example for now, and build it into something more advanced later.
Another one: I have started to write a contributors.md file to document how the examples work. Put a note on us not accepting community contributions just now. If you don't like publishing it (yet) then I could stick the text in to the internal repo for now so we can at least look at it and refine it?
We can publish it as a CONTRIBUTING.md in this repository and give it more visibility (e.g. in the README or on the docs) once we have figured out how we want to build examples and recipes in the future.
There was a problem hiding this comment.
One more thing: if you're on the contributing.md, it would be perfect if you could find some time to work on squidfunk/mkdocs-material#6153, which we're desperately missing in our docs. I guess there might be some overlap.
Hi @squidfunk, added an example for a stand-alone blog along the lines of the discussion in squidfunk/mkdocs-material#6395. I think we should let the OP there be involved in reviewing this, so will point them to this PR.