From 66bc11f0ea14cda59c5553f5e846804d2603a6ed Mon Sep 17 00:00:00 2001 From: madrilene Date: Sun, 4 Feb 2024 08:55:39 +0100 Subject: [PATCH] restructure docs page --- src/docs/design-tokens.md | 11 ++++++ src/docs/docs.json | 4 ++ src/docs/first.md | 26 +++++++++++++ src/docs/fonts.md | 13 +++++++ src/docs/further.md | 9 +++++ src/docs/more-features.md | 14 +++++++ src/docs/theme.md | 5 +++ src/pages/get-started.md | 77 --------------------------------------- src/pages/get-started.njk | 18 +++++++++ 9 files changed, 100 insertions(+), 77 deletions(-) create mode 100644 src/docs/design-tokens.md create mode 100644 src/docs/docs.json create mode 100644 src/docs/first.md create mode 100644 src/docs/fonts.md create mode 100644 src/docs/further.md create mode 100644 src/docs/more-features.md create mode 100644 src/docs/theme.md delete mode 100644 src/pages/get-started.md create mode 100644 src/pages/get-started.njk diff --git a/src/docs/design-tokens.md b/src/docs/design-tokens.md new file mode 100644 index 0000000..758b894 --- /dev/null +++ b/src/docs/design-tokens.md @@ -0,0 +1,11 @@ +--- +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. + +In the [style guide](/styleguide/) you can see how everything turns out. + +Please note that adjustments in `viewports.json` only affect your utility classes and custom properties, but do not change the dimensions of your page. You can control this using the custom property `--wrapper-width`. \ No newline at end of file diff --git a/src/docs/docs.json b/src/docs/docs.json new file mode 100644 index 0000000..901c604 --- /dev/null +++ b/src/docs/docs.json @@ -0,0 +1,4 @@ +{ + "tags": "docs", + "permalink": false +} diff --git a/src/docs/first.md b/src/docs/first.md new file mode 100644 index 0000000..4a0f72c --- /dev/null +++ b/src/docs/first.md @@ -0,0 +1,26 @@ +--- +title: First steps +--- + +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/fonts.md b/src/docs/fonts.md new file mode 100644 index 0000000..6a62658 --- /dev/null +++ b/src/docs/fonts.md @@ -0,0 +1,13 @@ +--- +title: Fonts +--- + +This starter uses three fonts, Red Hat Display, Figtree and Roboto Mono. 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). + +Next, edit `src/assets/css/global/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 diff --git a/src/docs/further.md b/src/docs/further.md new file mode 100644 index 0000000..bd3a8b3 --- /dev/null +++ b/src/docs/further.md @@ -0,0 +1,9 @@ +--- +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 new file mode 100644 index 0000000..891c31d --- /dev/null +++ b/src/docs/more-features.md @@ -0,0 +1,14 @@ +--- +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/theme.md b/src/docs/theme.md new file mode 100644 index 0000000..7265cb9 --- /dev/null +++ b/src/docs/theme.md @@ -0,0 +1,5 @@ +--- +title: Theme +--- + +This blog has a pagination of {{ pagination.size }} posts per page. diff --git a/src/pages/get-started.md b/src/pages/get-started.md deleted file mode 100644 index c428b81..0000000 --- a/src/pages/get-started.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Get started -permalink: /get-started/index.html -description: Websites built with this starter -layout: page -preloads: - href: '/assets/fonts/robotomono/robotomono-regular.woff2' - as: 'font' - type: 'font/woff2' - crossorigin: true ---- - -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`. - -## Change fonts - -This starter uses three fonts, Red Hat Display, Figtree and Roboto Mono. 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). - -Next, edit `src/assets/css/global/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`. - -## Edit the 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. - -In the [style guide](/styleguide/) you can see how everything turns out. - -Please note that adjustments in `viewports.json` only affect your utility classes and custom properties, but do not change the dimensions of your page. You can control this using the custom property `--wrapper-width`. - -## 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/). - -## 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/) diff --git a/src/pages/get-started.njk b/src/pages/get-started.njk new file mode 100644 index 0000000..36a900a --- /dev/null +++ b/src/pages/get-started.njk @@ -0,0 +1,18 @@ +--- +title: Get started +permalink: /get-started/index.html +description: Websites built with this starter +layout: page +preloads: + href: '/assets/fonts/robotomono/robotomono-regular.woff2' + as: 'font' + type: 'font/woff2' + crossorigin: true +--- + +{%- for entry in collections.docs -%} +
+ {{ entry.data.title }} +{{ entry.templateContent | safe }} +
+{%- endfor -%}