diff --git a/src/docs/css.md b/src/docs/css.md new file mode 100644 index 0000000..2f7158d --- /dev/null +++ b/src/docs/css.md @@ -0,0 +1,7 @@ +--- +title: CSS +--- + +Add and delete your custom block stylesheets in `src/assets/css/blocks/*.css`, they get pulled in your output stylesheet automatically. + +The methodology used is [CUBE CSS.](https://cube.fyi/) diff --git a/src/docs/delete.md b/src/docs/delete.md new file mode 100644 index 0000000..880db51 --- /dev/null +++ b/src/docs/delete.md @@ -0,0 +1,15 @@ +--- +title: What can be deleted +--- + +You can delete the following files and archives (the theme may break though, if there are still references to them): + +- `github.js` in `src/_data/` +- `builtwith.json` in `src/_data/` +- all the blog posts, as these serve only as an example +- the directoy and all files in `src/docs` +- all pages in `src/pages`, though you might want to keep `index.njk` as a starting point +- You can delete `screenshots`, `blog` and `gallery` in `src/assets/images`. + Keep the `favicon` and `template` folders though. + +If you don't want to feature any code examples, you may delete the whole stylesheet for syntax highlighting: `src/assets/css/blocks/code.css`. diff --git a/src/docs/first.md b/src/docs/first.md deleted file mode 100644 index 7f8c9ea..0000000 --- a/src/docs/first.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: First steps -date: 2024-01-01 ---- - -You can use this starter as a template for your blog and you are ready to go! But there are some adjustments you have to make, most of them in `src/_data/meta.js`. It sets different "hard coded" text values all over the template, you can change the language, etc. - -Also, edit personal your details and social media in `src/_data/personal.yaml`. - -Find available social media / service icons in `src/_includes/svg` (prefixed with "social-"). -If you add new icons they too must be prefixed with "social-". - -Open `src/assets/css/blocks/external-link.css`. Replace "eleventy-excellent.netlify.app" with your own domain. This is about the external link indicators, they are matched with your domain. If you don't want to use external link indicators, feel free to delete the whole style rule. You can also add the class `no-indicator` to any anchor element you want to except from this rule. - -Edit your navigation items in `src/_data/navigation.js`. - -Add your custom (favicon) icons in `src/assets/images/favicon`. - -Not required, but recommended: you can delete the following files and archives (the theme may break though, if there are still references to them): - -- `github.js` in `src/_data/` -- `builtwith.json` in `src/_data/` -- all the blog posts, as these serve only as an example -- all pages in `src/pages`, though you might want to keep `index.njk` as a starting point -- image folders "screenshots", "blog" and "gallery" in `src/assets/images` - -If you don't want to feature any code examples, you may delete the whole stylesheet for syntax highlighting: `src/assets/css/blocks/code.css`. \ No newline at end of file diff --git a/src/docs/further.md b/src/docs/further.md deleted file mode 100644 index bd3a8b3..0000000 --- a/src/docs/further.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Further adjustments ---- - -Optional: rename `.env-sample` to `.env`. You may set a custom URL for local development and add your own variables. - -Add and delete your custom block stylesheets in `src/assets/css/blocks/*.css`, they get pulled in your output stylesheet automatically. - -If you are working with **VS Code** I recommend installing the "Tailwind CSS IntelliSense" addon, as it works also for our custom utility classes. That said, you will find that Tailwind CSS does not work as you might expect. I exlain this in [one of the blog posts](/blog/what-is-tailwind-css-doing-here/). \ No newline at end of file diff --git a/src/docs/more-features.md b/src/docs/more-features.md deleted file mode 100644 index 891c31d..0000000 --- a/src/docs/more-features.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: More features ---- - -The [blog posts](/blog/) explain / show some basic features that aren't covered here: - -- [Galleries](/blog/post-with-a-gallery/) -- [Open Graph images](/blog/open-graph-images/) -- [Markdown](/blog/post-with-all-the-markdown/) -- [Youtube](/blog/post-with-a-video/) -- [Using the image plugin](/blog/post-with-an-image/) -- [Syntax highlighting](/blog/post-with-some-code/) -- [301 redirects](/blog/post-with-301-redirects/) -- [Fetch content](/blog/post-with-fetched-content/) \ No newline at end of file diff --git a/src/docs/open-graph.md b/src/docs/open-graph.md new file mode 100644 index 0000000..e219ec3 --- /dev/null +++ b/src/docs/open-graph.md @@ -0,0 +1,37 @@ +--- +title: Open Graph images +--- + +You can see a [preview of the OG images in a blog post](/blog/open-graph-images/). + +They are referenced in `meta-info.njk`: + +{% raw %} + +```html + +``` + +{% endraw %} + +To change the look and behaviour of those images and replace the SVG background edit `src/common/og-images.njk`. + +The implementation is based on [Bernard Nijenhuis article.](https://bnijenhuis.nl/notes/automatically-generate-open-graph-images-in-eleventy/) + +If you want to be inspired, have a look at [what Lea does here.](https://github.com/learosema/lea-codes/blob/main/src/opengraph-default.njk) + +Previously the images were created at build time, but this leads to not rendering the font - if the system executing the build has not installed it, it will not be generated. + +A solution would be to always build the page yourself and then place it on the server directly. Or, as [Sophie Koonin does](https://github.com/sophiekoonin/localghost/blob/main/eleventy.config.js#L45-L47), explicitly specify the system to be used for the build and select a font that this system has installed by default. + +At the moment I have relocated the creation of the images in the development process, so that the font only needs to be installed on your own system. The images are located in `src/assets/og-images` and are comitted. + +This is fine as long as you only work with markdown and the font is always installed on your system, how this works with a CMS workflow remains to be seen. + +Let me know if you encounter any problems. diff --git a/src/docs/platforms.md b/src/docs/platforms.md new file mode 100644 index 0000000..343919c --- /dev/null +++ b/src/docs/platforms.md @@ -0,0 +1,10 @@ +--- +title: Platforms (icons) +--- + +Find available social media / platform icons in `src/_includes/svg` (prefixed with `platform-`). +If you add new icons they too must be prefixed with "platform-". + +In `personal.yaml` you can add new platforms and their URLs. The key must be the same as the prefix of the icon. + +https://simpleicons.org/ features a great variety of free SVG icons for popular brands. diff --git a/src/docs/tags.md b/src/docs/tags.md new file mode 100644 index 0000000..ce54f33 --- /dev/null +++ b/src/docs/tags.md @@ -0,0 +1,50 @@ +--- +title: Tags +--- + +This was probably the most opinionated decision: tags have been integrated since version 2.0. + +In several places you will find a code block that looks like this: + +{% raw %} + +```html + +{% set itemList = collections.posts %} {% for item in itemList.slice(0, 4) %} + +{% set activateTags = true %} + +{% set headingContext = "h3" %} + +{% include 'components/card.njk' %} {% endfor %} +``` + +{% endraw %} + +Here `card.njk` is imported as a component, and some settings are made beforehand. In connection with tags, ` {% set activateTags = true %}` is important, because here you can switch off the display of tags in this card instance. + +The tags are in your collection items in the front matter with the syntax + +{% raw %} + +```md +tags: + - image + - feature +``` + +{% endraw %} + +or + +{% raw %} + +```md +tags: ['markdown', 'feature'] +``` + +{% endraw %} + +are entered. + +If you generally do not want any tags to show, it is probably easiest to not create any at all. diff --git a/src/docs/theme.md b/src/docs/theme.md index 7265cb9..1ae35b5 100644 --- a/src/docs/theme.md +++ b/src/docs/theme.md @@ -1,5 +1,13 @@ --- -title: Theme +title: Theme (dark / light mode) --- -This blog has a pagination of {{ pagination.size }} posts per page. +With version 2.0 I introduced dark and light mode. This is not intended to be a gimmick, but to support the accessibility of the site. And I tend to read blog posts at night, and if there is no dark mode then I leave the tab for later, and we all know how that ends. + +Dark and light mode respects the user agent or operating system settings using the `prefers-color-scheme` CSS media feature. But there is also a switch in the `