Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

added example for a stand-alone blog #14

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

added example for a stand-alone blog #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions examples/blog-standalone/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Creating a standalone blog

Sometimes it is desirable to set up a website that has a blog as its central
feature. Rather than being embedded into a wider website with its own complex
structure, the blog structure organizes most of the content.

This example shows how set up such a blog using the [blog plugin].

It shows how to:

- configure the `mkdocs.yml` to activate and configure the plugin
- set up navigation to prominently feature the blog structure
- set up a directory structure in your `docs/` folder
- add an `.authors.yml` file with author information

The naming of the files containing the blog posts is just a
suggestion, you can name them any way you like. What matters is the
meta data at in the header.

[blog plugin]: https://squidfunk.github.io/mkdocs-material/plugins/blog/



9 changes: 9 additions & 0 deletions examples/blog-standalone/docs/demo/.authors.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
authors:
squidfunk:
name: Martin Donath
description: Creator
avatar: https://github.com/squidfunk.png
alexvoss:
name: Alex Voss
description: Weltenwanderer
avatar: https://github.com/alexvoss.png
1 change: 1 addition & 0 deletions examples/blog-standalone/docs/demo/about/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# About...
Empty file added examples/blog-standalone/docs/demo/index.md
View file
Open in desktop
Empty file.
32 changes: 32 additions & 0 deletions examples/blog-standalone/docs/demo/posts/firstpost.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
authors:
- alexvoss
date: 2023-10-11
categories:
- meta
---

# My first blog post

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.

<!-- more -->

Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.

Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
tellus id elit ultricies, vel finibus erat cursus.

32 changes: 32 additions & 0 deletions examples/blog-standalone/docs/demo/posts/secondpost.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
authors:
- squidfunk
date: 2023-10-12
categories:
- hello
---

# A second post

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.

<!-- more -->

Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.

Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
tellus id elit ultricies, vel finibus erat cursus.

46 changes: 46 additions & 0 deletions examples/blog-standalone/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Copyright (c) 2016-2023 Martin Donath <[email protected]>
# Alex Voss <[email protected]>

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

# -----------------------------------------------------------------------------
# Recommended: set up configuration validation, see https://t.ly/xpZXU
# -----------------------------------------------------------------------------

# Project information
site_name: Standalone blog example

# Theme
theme:
name: material
features:
- navigation.tabs
- navigation.indexes

# Plugins
plugins:
- search
- blog:
blog_dir: demo
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the blog contained in the demo directory? IMHO, by definition, a standalone blog lives at the root 😅

Copy link
Contributor Author

@alexvoss alexvoss Nov 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

@squidfunk squidfunk Nov 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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???

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just came to realize that everything is about food 😂 Starters, cookbooks, recipes, ...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


nav:
- Our Blog:
- demo/index.md
- About:
- demo/about/index.md
21 changes: 21 additions & 0 deletions examples/blog-standalone/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Copyright (c) 2016-2023 Martin Donath <[email protected]>

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

mkdocs-material