From 08df6910fc1083573c32dd3c0c2d027fd4796afd Mon Sep 17 00:00:00 2001 From: madrilene Date: Mon, 3 Jun 2024 11:30:52 +0200 Subject: [PATCH] add and update docs --- src/docs/card.njk | 91 +++++++++++++++++++++++++++++++++++++++ src/docs/config.md | 56 ++++++++++++++++++++++++ src/docs/css.md | 32 ++++++++++++-- src/docs/design-tokens.md | 2 +- src/docs/details.md | 23 ++++++++++ src/docs/docs.json | 2 +- src/docs/easteregg.md | 23 ++++++++++ src/docs/favicons.md | 18 ++++++-- src/docs/fonts.md | 8 ++-- src/docs/javascript.md | 36 ++++++++++++++++ src/docs/less-js.md | 17 -------- src/docs/masonry.md | 38 ++++++++++++++-- src/docs/navigation.md | 3 +- src/docs/pagination.md | 4 +- src/docs/platforms.md | 7 ++- src/docs/svg.md | 24 +++++++++++ src/docs/tags.md | 22 ---------- src/docs/what-delete.md | 2 +- src/docs/youtube.md | 13 ++++++ 19 files changed, 356 insertions(+), 65 deletions(-) create mode 100644 src/docs/card.njk create mode 100644 src/docs/config.md create mode 100644 src/docs/details.md create mode 100644 src/docs/easteregg.md create mode 100644 src/docs/javascript.md delete mode 100644 src/docs/less-js.md create mode 100644 src/docs/svg.md create mode 100644 src/docs/youtube.md diff --git a/src/docs/card.njk b/src/docs/card.njk new file mode 100644 index 0000000..1ca75cb --- /dev/null +++ b/src/docs/card.njk @@ -0,0 +1,91 @@ +--- +title: Card +--- + +

+ Previous to version 3, the card component was a Nunjucks include. There are a number of things that had to + be set before being able to use it, like the level of the heading or whether tags shall be displayed. + WebC + makes this easier, as you can now use the custom element and opt in to the different slots. +

+ +

Available slots:

+ + +

I added some variants, avaliable via attribute selectors:

+ + + +Usage + +
{% raw %}
+  
+  <custom-card>
+	{% image "path-to-img", "alt-text" %}
+	<span slot="date"></span>
+	<span slot="tag" class="button post-tag"></span>
+	<h2 slot="headline"></h2>
+	<p slot="content"></p>
+	<footer slot="footer"></footer>
+	</custom-card>
+{% endraw %}
+ +Example + +
+ + {% image "./src/assets/images/gallery/asturias-3.jpg", "Close-up of a delicate white flower with a yellow center, surrounded by green leaves" %} + 1516 + Default +

Utopia

+

+ Among them, there is no sort of traffic, no knowledge of letters, no understanding of numbers, no name + of magistrates, nor of politics, only of virtues; and they measure all things by barleycorns; their + money, plate, and other ornaments they so diligently polish that no rust can stick to them. +

+ + + + + {% image "./src/assets/images/gallery/asturias-3.jpg", "Close-up of a delicate white flower with a yellow center, surrounded by green leaves" %} + 18.02.1984 +
+ clickablesquare image +
+ +

The order does not matter

+ + + +

+ They have no lawyers among them, for they consider them as a sort of people whose profession it is to + disguise matters and to wrest the laws [...]. +

+

Just title and content

+ + + + {% image "./src/assets/images/gallery/asturias-3.jpg", "Close-up of a delicate white flower with a yellow center, surrounded by green leaves" %} +

+ Red Hat's first logo appeared on an early invoice. It was a simple, bright red brimmed top hat placed + above the words "Red Hat Software." +

+

This card has no padding

+ +
diff --git a/src/docs/config.md b/src/docs/config.md new file mode 100644 index 0000000..6301fab --- /dev/null +++ b/src/docs/config.md @@ -0,0 +1,56 @@ +--- +title: Config +--- + +I like to divide things into small thematic areas, it helps me orient myself better. Configurations are structured into separate modules in `src/_config` and are then imported into the main configuration file. + +- **collections.js**: Manages Eleventy collections such as posts and tags: https://www.11ty.dev/docs/collections/ +- **events.js**: For code that should run at certain times during the compiling process: https://www.11ty.dev/docs/events/ +- **filters.js**: Used within templating syntax to transform data into a more presentable format: https://www.11ty.dev/docs/filters/ +- **plugins.js**: Everything I or Eleventy considers to be a plugin: https://www.11ty.dev/docs/plugins/ +- **shortcodes.js**: Defines shortcodes for reusable content: https://www.11ty.dev/docs/shortcodes/ + +Each configuration category (filters, plugins, shortcodes, etc.) is modularized. or example, `dates.js` within the `filters` folder contains date-related filters. + +```js +import dayjs from 'dayjs'; + +export const toISOString = dateString => dayjs(dateString).toISOString(); +export const formatDate = (date, format) => dayjs(date).format(format); +``` + +These individual modules are then imported and consolidated in a central `filters.js` file, which exports all the filters as a single default object. + +```js +import {toISOString, formatDate} from './filters/dates.js'; +// more imports + +export default { + toISOString, + formatDate, +// more exports +}; + +``` + +**Integration in Eleventy Config** + +In the main Eleventy configuration file (`eleventy.config.js`), these modules are imported: + +```js +import filters from './src/_config/filters.js'; +import shortcodes from './src/_config/shortcodes.js'; +``` + +They are then used to register filters and shortcodes with Eleventy, using this nice concise syntax: + +```js +eleventyConfig.addFilter('toIsoString', filters.toISOString); +eleventyConfig.addFilter('formatDate', filters.formatDate); +// More filters... +eleventyConfig.addShortcode('svg', shortcodes.svgShortcode); +``` + +This method hopefully keeps the Eleventy config clean and focused, only concerning itself with the registration of functionalities, while the logic and definition remain abstracted in their respective modules. + +Some time ago I wrote a blog post about [how to organize the Eleventy configuration file](https://www.lenesaile.com/en/blog/organizing-the-eleventy-config-file/) where I go a little bit deeper into this topic. \ No newline at end of file diff --git a/src/docs/css.md b/src/docs/css.md index 66d06ea..2a171f7 100644 --- a/src/docs/css.md +++ b/src/docs/css.md @@ -2,9 +2,35 @@ title: CSS --- -Add and delete your custom block stylesheets in `src/assets/css/blocks/*.css`, they get pulled in your output stylesheet automatically. +Add and delete your globally available custom block stylesheets in `src/assets/css/global/blocks/*.css`. The methodology used is [CUBE CSS.](https://cube.fyi/) -The CSS system of this starter was invented by Andy Bell. -If you want to know exactly how it all works, and have a look at the (further elaborated) original, [read this article on piccalil.li](https://piccalil.li/blog/a-css-project-boilerplate/). +The CSS system of this starter was invented by Andy Bell. If you want to know exactly how it all works, and have a look at the (further elaborated) original, [read this article on piccalil.li](https://piccalil.li/blog/a-css-project-boilerplate/). + +**New in version 3.0: Inline CSS** + +The main CSS file is now inline in production to improve performance, see `.src/_includes/head/css-inline.njk`. + +You can add per-page or component bundles of CSS. Instead of adding your CSS file to the `src/assets/css/global/blocks/` directory, you can place them in `src/assets/css/bundle/`. All CSS files in there will be stored alongside `global.css` in `.src/_includes/css/`. You can now include them in the "inline" bundle only on pages or components where you need them: + + +{% raw %} + +```jinja2 +{% css "inline" %} + {% include "css/your-stylesheet.css" %} +{% endcss %} +``` + +{% endraw %} + +**New in version 3.0: Component CSS** + +All CSS files placed in `src/assets/css/components/` will be sent to the output folder, where components can reference them: `/assets/css/components/*.css`. + +**New in version 3.0: Debugging CSS** + +In `src/assets/css/global.css` you can decomment `@import-glob 'tests/*.css';` to include CSS for debugging. + +It makes visible you when your code[ wrapped in `` elements](https://github.com/11ty/is-land) is being hydrated, where things might overflow and many other warnings and errors [that Heydon Pickering came up with](https://heydonworks.com/article/testing-html-with-modern-css/). \ No newline at end of file diff --git a/src/docs/design-tokens.md b/src/docs/design-tokens.md index 8814b5b..c238526 100644 --- a/src/docs/design-tokens.md +++ b/src/docs/design-tokens.md @@ -4,7 +4,7 @@ title: Design tokens Edit all your preferences (colors, fluid text sizes etc.) in `src/_data/designTokens/*.json`. -Additional colors, variants and gradients for custom properties are automatically created in `src/assets/css/global/variables.css` based on the colors set in `colors.json`. If you change names you should edit `variables.css` as well and check if the names are used elsewhere in the template. +Additional colors, variants and gradients for custom properties are automatically created in `src/assets/css/global/base/variables.css` based on the colors set in `colors.json`. If you change names you should edit `variables.css` as well and check if the names are used elsewhere in the template. Admittedly, I went a little bit crazy there with the new CSS color syntax stuff. In the [style guide](/styleguide/) you can see how everything turns out. diff --git a/src/docs/details.md b/src/docs/details.md new file mode 100644 index 0000000..ad9a874 --- /dev/null +++ b/src/docs/details.md @@ -0,0 +1,23 @@ +--- +title: Details +usage: "{% set itemList = collections.docs %}{% include 'partials/details.njk' %}" +--- + +The `custom-details` WebC component has a corresponding Nunjucks include. +It uses the `details` and `summary` elements to create a collapsible section and enhances them aesthetically and functionally. + +The JavaScript for the `custom-details` component adds functionality to buttons to expand and collapse the sections with one action. When JavaScript is disabled, the sections are still accessible and collapsible, but the extra buttons are hidden. + +On page load, it checks if a hash corresponding to a details ID exists in the URL. If such an ID is found, the corresponding details section is programmatically opened, allowing direct navigation to an open section from a shared URL. + +The sorting is set by default on "alphabetic", but you can also pass in "shuffle" or "reverse" as a parameter (directly in the `details.njk` partial). + +**Usage** + +``` +{{ usage | safe }} +``` + +**Example** + +You are in the middle of a custom details component! \ No newline at end of file diff --git a/src/docs/docs.json b/src/docs/docs.json index 901c604..c5341b9 100644 --- a/src/docs/docs.json +++ b/src/docs/docs.json @@ -1,4 +1,4 @@ { - "tags": "docs", + "tags": "docs", "permalink": false } diff --git a/src/docs/easteregg.md b/src/docs/easteregg.md new file mode 100644 index 0000000..f5d9f74 --- /dev/null +++ b/src/docs/easteregg.md @@ -0,0 +1,23 @@ +--- +title: Easteregg +--- + +The `custom-easteregg` component is by default in the base layout in `src/_layouts/base.njk`. Just delete the two lines if you don't want to use it. The component is + designed to trigger a confetti effect when a user types a specific keyword sequence. It uses the dynamic import of the `canvas-confetti` library to render custom-shaped particles based on user input. + +**Defaults**: + - **Keywords**: `"eleventy"`, `"excellent"` + - **Shape**: `"⭐️"` + - **Particle Count**: `30` + +**Customizable Attributes**: + - `keyword`: custom keyword + - `shape`: custom shape for the confetti particles using emojis or text + - `particle-count`: number of particles to release during the effect + + +``` + + +``` + diff --git a/src/docs/favicons.md b/src/docs/favicons.md index 16605bc..533590f 100644 --- a/src/docs/favicons.md +++ b/src/docs/favicons.md @@ -2,10 +2,20 @@ title: Favicons --- -The favicons used are based on the recommendations from the [How to Favicon article on evilmartians.com.](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs) +All "necessary" favicons are in `src/assets/images/favicon`, and copied over to the root of the output folder. -All favicons are in `src/assets/images/favicons`, and copied over to the root of the output folder. +I chose the sizes based on the recommendations from the [How to Favicon article on evilmartians.com.](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs) -There is no automatization in place to create them. +You can place them in that directory manually, or use the script to autmate the process: -I recommend keeping the file names as they are, since they are referenced like that in different places. +```bash +npm run favicons +``` + +In this case define the SVG icon on which all formats are based on in `meta.js`: + +```js +export const pathToSvgLogo = 'src/assets/svg/misc/logo.svg'; // used for favicon generation +``` + +Regardless of whether you generate the icons automatically or create them manually, it is best to keep the names so as not to break any reference to them. diff --git a/src/docs/fonts.md b/src/docs/fonts.md index 6a62658..b4b4428 100644 --- a/src/docs/fonts.md +++ b/src/docs/fonts.md @@ -2,12 +2,12 @@ title: Fonts --- -This starter uses three fonts, Red Hat Display, Figtree and Roboto Mono. You can add or delete fonts in `src/assets/fonts`. +This starter uses two custom fonts, Red Hat Display and Inclusive Sans. You can add or delete fonts in `src/assets/fonts`. -You can create font subsets for a better performance, for example using the [Fontsquirrel Webfont Generator](https://www.fontsquirrel.com/tools/webfont-generator). +I often create font subsets using the [Fontsquirrel Webfont Generator](https://www.fontsquirrel.com/tools/webfont-generator). -Next, edit `src/assets/css/global/fonts.css`. +Next, edit `src/assets/css/global/base/fonts.css`. Add your new font aliases in `src/_data/designTokens/fonts.json`. -Finally, in `src/_layouts/base.njk` edit the font preloads. Roboto Mono is only used for code blocks. Its preload is set directly in the post layout: `src/_layouts/post.njk`. \ No newline at end of file +Finally, in `src/_includes/head/preloads.njk` edit the font preloads. diff --git a/src/docs/javascript.md b/src/docs/javascript.md new file mode 100644 index 0000000..20d9e60 --- /dev/null +++ b/src/docs/javascript.md @@ -0,0 +1,36 @@ +--- +title: JavaScript +--- + +This starter has **no real JS dependency**. If JavaScript is not available, components that rely on it -- like the theme switcher -- will be hidden. If you opted in for the drawer menu, pills will be shown instead. + +There are two kinds of bundles for JavaScript in this starter, see `.src/_includes/head/js-inline.njk` and `.src/_includes/head/js-defer.njk`. +By default, I include Eleventy's [is-land](https://github.com/11ty/is-land) framework and the theme toggle inline. + +You can include more scripts like so: + +{% raw %} + +```jinja2 +{% js "inline" %} + {% include "scripts/your-inline-script.js" %} +{% endjs %} +``` + +{% endraw %} + +Same goes for scripts that should be defered: + +{% raw %} + +```jinja2 +{% js "defer" %} + {% include "scripts/your-defered-script.js" %} +{% endjs %} +``` + +{% endraw %} + +Scripts stored in `src/assets/scripts/components/` are sent to the output folder, while scripts in `src/assets/scripts/bundle/` are sent to `.src/_includes/scripts/`, from where you can include them in the respective bundle. + +Some components are enhanced with JavaScript. \ No newline at end of file diff --git a/src/docs/less-js.md b/src/docs/less-js.md deleted file mode 100644 index 49a1b53..0000000 --- a/src/docs/less-js.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Less JavaScript ---- - -The only "real" JavaScript dependency is **theme-toggle.js**, which is inlined. - -The `gallery.njk` and `details.njk` components were slightly enhanced with JavaScript. - -There are three more scripts, but you have to opt in: - -**nav-drawer.js**, to opt in to a drawer menu on small screens (Read more in **Navigation**). - -**masonry.js**, creating the masonry effect used on the cards. -Search for `masonry: true` to see where it is activated, and set to `false`, an empty string, or delete the front matter field, if you don't want to use it. The script won't be included then. Nothing breaks, the cards just won't rise up to completely fill the gaps in their grid. - -The **easteregg.js** is an opt-in JS-file set in `src/_data/meta.js`. -Right to the end of the file, you can set `easteregg: false` to deactivate the loading of the script. diff --git a/src/docs/masonry.md b/src/docs/masonry.md index 37dbf0f..b262fd8 100644 --- a/src/docs/masonry.md +++ b/src/docs/masonry.md @@ -2,8 +2,38 @@ title: Masonry --- -There is the idea of making masonry layout a native part of CSS grid, using `grid-template-rows: masonry;`. It is [not yet to be seen on the horizon](https://caniuse.com/mdn-css_properties_grid-template-rows_masonry), but it is already included in the starter (inside the `grid.css` composition). -Until then, a small script will help us to get the effect. -It gets loaded by opt-in. -Set `masonry: true` in your front matter to activate. +Masonry layout is not yet a native part of CSS grid. There is a debate if using `grid-template-rows: masonry;` is actually the best way to implement it. + +It should be used carefully so we don't create confusion with the tabbing order. In version 3 of the starter I made the masonry layout a web component, and no longer a opt-in feature (was: `masonry: true` in the front matter). + +`custom-masonry` is designed to function as a masonry grid by dynamically adjusting item positions based on the available column space and the size of its content. The necessary JavaScript (`custom-masonry.js`) is loaded only once per component usage due to the `data-island="once"` attribute. +Optional: pass in `layout="50-50"` to set a 50% width for each column. + +If no JavaScript is available, the grid will fall back to the regular grid layout defined in `src/assets/css/global/compositions/grid.css`. + +``` + (children) + (children) +``` + +
+
+
+
+
+
+
+
+
+
+
+
+ + \ No newline at end of file diff --git a/src/docs/navigation.md b/src/docs/navigation.md index 754fbc6..8a21228 100644 --- a/src/docs/navigation.md +++ b/src/docs/navigation.md @@ -6,13 +6,12 @@ Edit your navigation items in `src/_data/navigation.js`. You have two options for mobile navigation: by default, the navigation on small displays is converted to small pills that wrap. This does not require any additional JavaScript. -Before version 2.0 a slide out drawer was the default, you can activate it again in `src/_data/meta.js`: +You can activate a drawer menu in `src/_data/meta.js`: ```js navigation: { // other settings drawerNav: true, - navLabel: 'Menu' }, ``` diff --git a/src/docs/pagination.md b/src/docs/pagination.md index 25ab546..ec07331 100644 --- a/src/docs/pagination.md +++ b/src/docs/pagination.md @@ -2,7 +2,7 @@ title: Pagination --- -The blog posts use [Eleventy's pagination feature](https://www.11ty.dev/docs/pagination/). The logic for this can be found in the layout `src/_layouts/blog.njk`, how many entries should be on a page can be defined in `src/pages/blog.md`. +The blog posts use [Eleventy's pagination feature](https://www.11ty.dev/docs/pagination/). The logic for this can be found in tha partial `src/_includes/partials/pagination.njk`, the layout `src/_layouts/blog.njk` includes it, how many entries should be on a page is defined in `src/pages/blog.md`. If you do not want any pagination at all, it is easiest to set a very high number for the pagination size, for example: @@ -44,7 +44,7 @@ and where the pagination component is included: `src/_layouts/blog.njk`: {% if collectionToPaginate.length > pagination.size %} -{% include 'components/pagination.njk' %} +{% include 'partials/pagination.njk' %} {% endif %} ``` diff --git a/src/docs/platforms.md b/src/docs/platforms.md index e5207a8..8b7c194 100644 --- a/src/docs/platforms.md +++ b/src/docs/platforms.md @@ -2,9 +2,8 @@ title: Platforms (icons) --- -Find available social media / platform icons in `src/_includes/svg` (prefixed with `platform-`). -If you add new icons, prefix their name with "platform-". +Find and set your platform icons in `src/assets/svg`, in the "platform" directory. -In `personal.yaml` you can add new platforms and their URLs. The key should be the same as the name of the icon. For example: `mastodon: 'https://front-end.social/@lene'` and `platform-mastodon.svg`. +In `src/_data/personal.yaml` you can edit the platforms. The key should be the same as the name of the icon. For example: `mastodon: 'https://front-end.social/@lene'` and `src/assets/svg/platform/mastodon.svg`. -https://simpleicons.org/ features a great variety of free SVG icons for popular brands. +https://simpleicons.org/ features a great variety of free SVG icons for popular platforms. diff --git a/src/docs/svg.md b/src/docs/svg.md new file mode 100644 index 0000000..96cdf48 --- /dev/null +++ b/src/docs/svg.md @@ -0,0 +1,24 @@ +--- +title: SVG +--- + +All SVG icons used in the starter are in `src/assets/svg`. There is a directory dedicated to the dividers, the platform icons and a general folder called "misc". + +**Shortcode** + +The `svg.js` shortcode, introduced in version 3, allows for the seamless inclusion of SVG files. Located in `src/_config/shortcodes/svg.js`, this shortcode requires only the folder and file name of the SVG, omitting the file extension. By default, SVGs are injected with an `aria-hidden="true"` attribute. The SVGs should be stored in the `src/assets/svg` directory, and referenced using the format `"folder/svg-name"`. + + +{% raw %} +```jinja2 +{% svg "path", "aria-name", "class-name", "inline-style" %} +{% svg "misc/star", "A yellow star icon", "spin", "block-size: 4ex; fill: var(--color-tertiary);" %} +``` +{% endraw %} + +{% svg "misc/star", "A yellow star icon", "spin", "block-size: 4ex; fill: var(--color-tertiary);" %} + +The star icon resoves to: + +` (...) ` + diff --git a/src/docs/tags.md b/src/docs/tags.md index cb1e1fc..8eeb255 100644 --- a/src/docs/tags.md +++ b/src/docs/tags.md @@ -4,28 +4,6 @@ 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 %} - -```jinja2 - -{% set itemList = collections.posts %} -{% for item in itemList.slice(0, 4) %} - -{% set activateTags = true %} - -{% set headingContext = "h3" %} - -{% include 'components/card.njk' %} -{% endfor %} -``` - -{% endraw %} - -`card.njk` is imported as a component, and some settings are made. -With `set activateTags = true` you can switch the display of tags in this card collection instance. - The tags are placed in the front matter of the posts, using the syntax ```yaml diff --git a/src/docs/what-delete.md b/src/docs/what-delete.md index 79b9b42..a2305a3 100644 --- a/src/docs/what-delete.md +++ b/src/docs/what-delete.md @@ -14,5 +14,5 @@ If you want to keep the defaults, but get rid of the example content, delete the - 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`. +If you don't want to feature any code examples, you may delete the whole stylesheet for syntax highlighting: `src/assets/css/global/blocks/code.css`. In general, any CSS block in there is optional. diff --git a/src/docs/youtube.md b/src/docs/youtube.md new file mode 100644 index 0000000..01f605b --- /dev/null +++ b/src/docs/youtube.md @@ -0,0 +1,13 @@ +--- +title: Youtube +--- + +The `@slug` attribute is used to pass the video ID to the `lite-youtube` element. +`@label` ist used for the nested `custom-youtube-link` which adds a link to watch on YouTube. This also serves as a fallback in case JS is deactivated. +Uses the [Lite YouTube Embed repository](https://github.com/paulirish/lite-youtube-embed). + +``` + +``` + +