diff --git a/README.md b/README.md index 871b6b5..e2bee47 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Decentral Patterns Website +# decentpatterns.xyz This repository holds the sources for the [decentpatterns.xyz](https://decentpatterns.xyz) website. It's built using the static site generator Eleventy, the tailwindcss framework and Javascript. @@ -20,9 +20,19 @@ To start the development server, run the `npm start` command in terminal and ope We use prettier and eslint to maintain a consistent and maintainable code style. Use the npm commands `npm run lint` to validate sources and `npm run prettier` to reformat sources on disk. +## Content Updates + +The bulk of the content - the pattern library - is organized in an [external repository](https://github.com/simplysecure/dots-patterns) that is included as a submodule at `/dots-patterns`. Whenever changes to that repository are made, a combination of Github Actions publishes the changes automatically. Here is how that happens: + +1. Changes are pushed to `dots-patterns/master` +2. The Github action ["Update dots-website"](https://github.com/simplysecure/dots-patterns/blob/master/.github/workflows/update-website.yml) runs in `dots-patterns` and calls the Github action "Update pattern library" in `dots-website` by issuing an http request. +3. The Github action ["Update pattern library"](https://github.com/simplysecure/dots-website/blob/develop/.github/workflows/update-patterns.yml) in `dots-website` updates the `dots-patterns` submodule and makes an automatic commit to the master branch. +4. Pushing to the master branch triggers a rebuild by Netlify +5. The changes are published. + ## Folder Structure -### Content +### Editing site content The `site` folder contains all the templates, partials and content - which Eleventy will parse into HTML for us. Within our `site` folder, lives a `globals` folder. Here you'll find a `site.json` file - for general config stuff e.g site name, author, email, social media links etc. You'll also find a `navigation.json` file, which we use to loop over in our nav partial to generate our navigation. It's possible to hide navigation entries from the production deployment by setting `"draft": true` on them. There's also a `helpers.js` file, which just contains a simple environment helper. @@ -41,5 +51,3 @@ The repository root contains configuration files for the various tools we use. I ## Ready to deploy? Type the `npm run build` command to minify scripts, styles and run Purgecss. - -Purge will cross reference your templates/HTML with all those Tailwind classes and will remove any classes you haven't used - pretty cool huh? diff --git a/public/sample-1.png b/public/sample-1.png new file mode 100644 index 0000000..ee84673 Binary files /dev/null and b/public/sample-1.png differ diff --git a/site/_globals/helpers.js b/site/_globals/helpers.js index aed350c..6cc4b83 100644 --- a/site/_globals/helpers.js +++ b/site/_globals/helpers.js @@ -22,14 +22,14 @@ const getRelatedPatterns = (data) => { } }; +/** + * Return the category name given pattern data, which contains the category slug + */ const categoryName = (data) => { const category = data.collections.topic.find( (t) => t.data.slug === data.topic ); if (category == null) { - // console.error( - // `Category ${data.topic} for pattern ${data.title} not found.` - // ); return `Category ${data.topic} not found`; } return category.data.title; diff --git a/site/_globals/library.json b/site/_globals/library.json deleted file mode 100644 index 7471a52..0000000 --- a/site/_globals/library.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "featured": "conditional-file-sharing" -} diff --git a/site/_includes/layouts/website-contributions.njk b/site/_includes/layouts/website-contributions.njk new file mode 100644 index 0000000..c95a5d7 --- /dev/null +++ b/site/_includes/layouts/website-contributions.njk @@ -0,0 +1,10 @@ +--- +layout: article +--- + + + +{{ content | safe }} diff --git a/site/contribute/dots-website/create-pattern.md b/site/contribute/dots-website/create-pattern.md new file mode 100644 index 0000000..c303168 --- /dev/null +++ b/site/contribute/dots-website/create-pattern.md @@ -0,0 +1,71 @@ +--- +title: Writing new patterns +layout: layouts/website-contributions.njk +--- + +# Writing new patterns + +Before you start writing a new pattern, [get in touch](https://decentpatterns.xyz/contribute/) with the dots community to announce and discuss your idea! + +## Step by Step + +New patterns are added to the website by creating a new folder in the [`dots-patterns` repository's `patterns`](https://github.com/simplysecure/dots-patterns/tree/master/patterns) folder. + +Here we are going to create the "Address" pattern as an example. + +1. Create a folder `patterns/address` in the `dots-patterns` repository. +2. Create a file with the name `index.md` inside your new folder. +3. Write your pattern using Markdown syntax (see [Pattern Text](#pattern-text)). +4. Add metadata for the pattern at the top of the file (see [Adding Metadata](#metadata)). +5. Add a large illustration for your pattern as a file `illustration.svg` and a thumbnail version as `thumbnail.svg` (see [Formatting Illustrations](#illustrations)). +6. Create a pull request on Github.com and request a review from a project maintainer. +7. See your new pattern appear on the DOTS website after your pull request is merged! + +## Pattern Text + +### Structure + +Every pattern starts with a general description of the design problem. We first want to quickly answer the question, "What makes the user story particularly interesting or different when the application uses decentralized technology?" Readers should then be able to understand how the pattern solves this problem, why one would choose this pattern (and why not), and real-world examples of where it has been used. + +[See the full pattern template here](https://github.com/simplysecure/dots-patterns/issues/new?assignees=&labels=pattern-submission&template=pattern-proposal-template.md&title=%5Bsubmission%5D) + +### Related Patterns and Wikilinks + +All the patterns of the library should be interlinked. Patterns don't stand alone, they are connected and in relation to other patterns. Use Wikilinks to add links to other patterns to your pattern text. They are formatted like + + [[pattern name]] + +and automatically converted to hyperlinks. Adding a wikilink to a pattern also adds the linked pattern to the _related patterns_ section of the pattern page. + +### Examples + +Include examples of your pattern in the wild in the form of screenshots. Place the image files for these screenshots in your pattern's directory and make sure they are in an adequate size and compression - keep in mind that some visitors of the library may have limited internet bandwidth. + +You can then use the `::: examples` syntax to include your examples in the pattern. Please see existing patterns or the [Markdown style guide](../style-guide-markdown) for examples of this. Make sure to include an _alt text_ of the image and a _description_ of the example. + +## Metadata + +Metadata lets us embed your new pattern in the right places in the website. You can add metadata to your pattern by inserting the following lines at the top of the `index.md` file. + +``` +--- +title: A title for your pattern +topic: your-topic +description: "A description of your pattern" +--- +``` + +Add a title and short description to this template. + +Select a fitting category for your pattern by entering one of the following choices in the `topic:` line: + +- identity-agency +- moderation-curation +- sharing-permissions +- sync-status + +See the [pattern library page](http://decentpatterns.xyz/library) for descriptions of these topics. + +## Illustrations + +Help needed! We need help describing the image format used for the existing illustrations so that new illustrations may be created in similar style and size. diff --git a/site/contribute/dots-website/index.md b/site/contribute/dots-website/index.md new file mode 100644 index 0000000..5b4d3bd --- /dev/null +++ b/site/contribute/dots-website/index.md @@ -0,0 +1,34 @@ +--- +layout: article +title: Contributing to the DOTS website +body_class: contribute-website +--- + +# Contributing to the DOTS website + +Here you find ressources that can help when editing this website. + +## README.md + +Please refer to the project [README](https://github.com/simplysecure/dots-website/tree/master/README.md) for information on how to set up a development environment and some helpful pointers on the directory structure, the `dots-patterns` subrepo and Github actions used to commission the site. + +## Style Guides + +There are style guides that help when creating pages using [Nunjucks](./style-guide-nunjucks) and [Markdown](./style-guide-markdown). They contain commonly used elements that can be copied from the guide's source code. + +## Writing a new pattern + +Refer to [this guide](./create-pattern) and look at the sources for existing patterns when creating new ones. + +## Adding new pages to the DOTS website + +A couple of things to keep in mind when creating new content on the DOTS website (that is not a pattern): + +- Add new pages by creating `.md` or `.njk` files in the `site` directory and its subdirectories. +- Add a YAML-formatted section delineated by dashes (`---`) to define metadata for the page + - Use `layout: default` to inject header, footer and base styles into your new page + - Use `layout: article` for additional styles that make reading content easier + - Use `title: ` to give your page a `` HTML tag + - Add a line `body_class: <page_name>` with your page name to apply an HTML id to the whole page that can be used for applying page-specific styles (see next tip) +- SCSS styles are available globally and included from `styles/main.scss`, which imports scss from various files in that directory. + - Add a scss file in `styles/pages/<pagename>.scss`, include it in `styles/pages/_all.scss` and define rules for your page by placing them inside a `#<page_name>` selector in that file. Refer to `style-guide.scss` and `style-guide-nunjucks.njk` for an example. diff --git a/site/contribute/dots-website/style-guide-markdown.md b/site/contribute/dots-website/style-guide-markdown.md new file mode 100644 index 0000000..11fe4d6 --- /dev/null +++ b/site/contribute/dots-website/style-guide-markdown.md @@ -0,0 +1,47 @@ +--- +layout: layouts/website-contributions.njk +body_class: style-guide-markdown +title: Markdown Style Guide +--- + +# Markdown Style Guide + +This page provides examples that can be copied when creating new pages using Markdown. Find the source code at: + +[`/site/contribute/dots-website/style-guide-markdown.md`](http://github.com/simplysecure/dots-website/blob/master/site/contribute/dots-website/style-guide-markdown.md) + +<a class="link-reference" href="../style-guide-nunjucks">Nunjucks Style Guide</a> + +# Heading 1 + +## Heading 2 + +### Heading 3 + +#### Heading 4 + +Paragraph + +Footnote[^1] + +- list +- of +- items + +[link](http://decentpatterns.xyz) + +> quote + +## Example images + +::: examples + +- [![image alt text](/files/sample-1.png) Description](/files/sample-1.png) + +- [![image 2 alt text](/files/sample-1.png) Description 2](/files/sample-1.png) + +::: + +## Footnotes + +[^1]: Footnote text diff --git a/site/contribute/dots-website/style-guide-nunjucks.njk b/site/contribute/dots-website/style-guide-nunjucks.njk new file mode 100644 index 0000000..02ad1bf --- /dev/null +++ b/site/contribute/dots-website/style-guide-nunjucks.njk @@ -0,0 +1,110 @@ +--- +layout: layouts/website-contributions.njk +title: Nunjucks Style Guide +body_class: style-guide +--- + +<section class="max-w-xl block"> + <h1>Nunjucks Style Guide</h1> + <p>This page provides examples that can be copied when creating new content for Nunjucks-formatted pages. Find the source code at: + </p> + <pre><a href="http://github.com/simplysecure/dots-website/blob/master/site/contribute/dots-website/style-guide-nunjucks.njk">/site/contribute/dots-website/style-guide-nunjucks.njk</a></pre> + <p> + <a class="link-reference" href="../style-guide-markdown">Markdown Style Guide</a> + </p> +</section> + +<section> + <div> + <h2>Typography</h2> + </div> + + <div class="content"> + <h1>Heading 1</h1> + <h2>Heading 2</h2> + <h3>Heading 3</h3> + <h4>Heading 4</h4> + <p>Paragraph</p> + + <p>Use the <span class="font-mono text-highlight">content</span> css-class on a container to restrict the width of text and create readable spacing between consecutive paragraphs, lists, etc.</p> + </div> +</section> + +<section> + <div> + <h2>Buttons</h2> + </div> + + <div> + <p> + <a class="btn">Button</a> + <a class="btn btn-primary">Primary button</a> + <a class="btn btn-secondary">Secondary button</a> + </p> + <p> + <a class="btn btn-pill">Pill button</a> + <a class="btn btn-sm">Small button</a> + <a class="btn btn-lg">Large button</a> + </p> + <p> + <div class="button-group"> + <a class="btn">Button 1</a> + <a class="btn">Button 2</a> + <a class="btn">Button 3</a> + </div> + </p> + </div> +</section> + +<section> + <div> + <h2>Links</h2> + </div> + + <div> + <h3>Linking to related content</h3> + <p> + <a class="link-reference">Reference</a> + </p> + + <h3>Paging and navigation in hierarchies</h3> + <div class="flex flex-row justify-between w-full"> + + <a class="link-prev" href="#"> + <img role="presentation" src="/images/icons/back.svg" /> + <div>Previous</div> + </a> + + <a class="link-next" href="#"> + <div>Next</div> + <img src="/images/icons/forward.svg" /> + </a> + + </div> + + <div class="flex flex-row justify-between w-full"> + + <a class="link-prev link-small" href="#"> + <img role="presentation" src="/images/icons/back.svg" /> + <div>Previous</div> + </a> + + <a class="link-next link-small" href="#"> + <div>Next</div> + <img src="/images/icons/forward.svg" /> + </a> + + </div> + </section> + + <section> + <div> + <h2>Pattern preview</h2> + </div> + + <div> + <p class="mb-12">This works best when the page data includes the pattern that you want to preview.</p> + {% patternPreview collections.patternsByTitle[0] %} + + </div> + </section> diff --git a/site/contribute.njk b/site/contribute/index.njk similarity index 100% rename from site/contribute.njk rename to site/contribute/index.njk diff --git a/styles/base/_typography.scss b/styles/base/_typography.scss index b8f6d58..e888e23 100644 --- a/styles/base/_typography.scss +++ b/styles/base/_typography.scss @@ -68,6 +68,14 @@ ol + p { } } +pre { + @apply my-8 pl-4 text-secondary; +} + +code { + @apply text-secondary; +} + .content { p, ul, diff --git a/styles/components/_all.scss b/styles/components/_all.scss index 3f04f64..df160e2 100644 --- a/styles/components/_all.scss +++ b/styles/components/_all.scss @@ -8,13 +8,10 @@ @import "_footer"; @import "_main"; -@import "donate"; @import "examples"; @import "featured-pattern"; -@import "offers"; @import "pattern-listing"; @import "pattern-main"; @import "pattern-preview"; @import "pattern"; -@import "report"; @import "timeline"; diff --git a/styles/components/_buttons.scss b/styles/components/_buttons.scss index 26d005e..cf304ec 100644 --- a/styles/components/_buttons.scss +++ b/styles/components/_buttons.scss @@ -1,27 +1,4 @@ //========== Buttons ==========// -// a.button, -// .buttons a { -// display: inline-block; -// @apply border-2 border-white py-1 px-2 rounded-lg text-highlight; -// font-weight: bold; -// border-width: 1px; - -// @screen md { -// @apply py-2 px-4; -// } -// } - -// .buttons { -// @apply my-6; - -// a { -// @apply mr-1; - -// @screen md { -// @apply mr-2; -// } -// } -// } .button-group { @apply flex flex-row; diff --git a/styles/components/links.scss b/styles/components/links.scss index 01bea3e..6e9935e 100644 --- a/styles/components/links.scss +++ b/styles/components/links.scss @@ -55,7 +55,7 @@ } &.link-small { - div:last-child { + :last-child { @apply w-8 h-8; } } @@ -78,7 +78,7 @@ } &.link-small { - div:first-child { + :first-child { @apply w-8 h-8; } } diff --git a/styles/main.scss b/styles/main.scss index a575ca1..f65c384 100644 --- a/styles/main.scss +++ b/styles/main.scss @@ -9,8 +9,9 @@ // Import Tailwind components @tailwind components; -// Import our custom component styles +// Import our custom component and page styles @import "components/all"; +@import "pages/all"; // Import Tailwind utilities // TailwindCSS recommends leaving utilities till last to ensure they aren't overwritten. diff --git a/styles/pages/_all.scss b/styles/pages/_all.scss new file mode 100644 index 0000000..adec6b4 --- /dev/null +++ b/styles/pages/_all.scss @@ -0,0 +1,4 @@ +@import "donate"; +@import "offers"; +@import "report"; +@import "style-guide"; diff --git a/styles/components/donate.scss b/styles/pages/donate.scss similarity index 100% rename from styles/components/donate.scss rename to styles/pages/donate.scss diff --git a/styles/components/offers.scss b/styles/pages/offers.scss similarity index 100% rename from styles/components/offers.scss rename to styles/pages/offers.scss diff --git a/styles/components/report.scss b/styles/pages/report.scss similarity index 100% rename from styles/components/report.scss rename to styles/pages/report.scss diff --git a/styles/pages/style-guide.scss b/styles/pages/style-guide.scss new file mode 100644 index 0000000..f234e7b --- /dev/null +++ b/styles/pages/style-guide.scss @@ -0,0 +1,32 @@ +#style-guide { + section { + @apply flex flex-col mb-32; + + // Introduction + &:first-of-type { + @apply block max-w-xl; + } + + @screen lg { + @apply flex-row; + } + + // Heading + div:nth-child(1) { + @screen lg { + @apply w-1/3 pr-12; + + h2 { + @apply mt-0; + } + } + } + + // Content + div:nth-child(2) { + & > :first-child { + @apply mt-0; + } + } + } +}