Document interactive components in playground

.github/workflows/deploy.yml

@@ -1,8 +1,13 @@
+# Copyright 2021 Marius Wilms, Christoph Labacher. All rights reserved.
+#
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
+
 name: Deploy
 on:
   push:
     branches:
-      - master
+      - main
 
 jobs:
   dsk:
@@ -105,4 +110,4 @@ jobs:
             --itemize-changes \
             assemblage/ deploy@${{ secrets.deploy_host }}:/var/www/dsk_website
 
-          ssh -o StrictHostKeyChecking=no deploy@${{ secrets.deploy_host }} 'sudo hoictl --project=/var/www/dsk_website load'
+          ssh -o StrictHostKeyChecking=no deploy@${{ secrets.deploy_host }} 'sudo hoictl --project=/var/www/dsk_website load'

10_The Design Definitions Tree/02_Documents/01_Playground/Readme.md

@@ -1,7 +1,48 @@
-<Banner title="Version Feature">
-  This is a feature of the redesigned frontend and available with version 1.2.
-</Banner>
-
 # Playgrounds
 
-If you place a document called `playground.md` amongst your [documents](/The-Design-Definitions-Tree/Documents) for one [aspect](/The-Design-Definitions-Tree/Aspects) in the design defintions tree, its contents will be displayed in a large [Playground](The-Design-Definitions-Tree/Documents/Components/Playground) on the top of the aspect’s page in DSK. This is helpfull to display a general demo of the aspect, so your users can immediatly see what the aspect is about. You can see an example of this in the documentation for some of the frontend’s documentation components, e.g. the [Banner](The-Design-Definitions-Tree/Documents/Components/Banner).
+Playgrounds are used to demonstrate components. To embed a playground 
+inside a document use the `<Playground>` tags.
+
+<Playground>
+  <Avatar name="Marius Wilms" email="[email protected]" />
+</Playground>
+
+```html
+<Playground>
+  <Avatar name="Marius Wilms" email="[email protected]" />
+</Playground>
+```
+
+## Annotating Components
+
+With annotations you can highlight specific points on the playground and add a comment.
+
+<Playground src="annotations.json">
+  {Component}
+</Playground>
+
+```html
+<Playground src="annotations.json">
+  {Component}
+</Playground>
+```
+
+### Annotations File Format
+
+The annotations specification file has to be formatted like this (`annotationColor` is optional):
+
+<CodeBlock src="annotations.json" language="json"></CodeBlock>
+
+## Large Standalone Playgrounds
+
+If you place a document called `playground.md` amongst your 
+[documents](/The-Design-Definitions-Tree/Documents) for one 
+[aspect](/The-Design-Definitions-Tree/Aspects) in the design 
+defintions tree, its contents will be displayed in a large 
+[Playground](The-Design-Definitions-Tree/Documents/Components/Playground) 
+on the top of the aspect’s page in DSK. This is helpfull to display a
+general demo of the aspect, so your users can immediatly see what the
+aspect is about. You can see an example of this in the documentation
+for some of the frontend’s documentation components, e.g. the
+[Banner](The-Design-Definitions-Tree/Documents/Components/Banner).
+

10_The Design Definitions Tree/02_Documents/01_Playground/meta.yaml

@@ -1,3 +1,5 @@
+description: A playground is a distinct space to display a component from your Design System.
 tags:
-  - needs description
   - special document
+  - documentation
+  - components

10_The Design Definitions Tree/02_Documents/10_Components/02-Code Block/01-Readme.md

@@ -1,7 +1,3 @@
-<Banner title="Version Feature">
-  Documentation components are available since version 1.2.
-</Banner>
-
 # Examples
 
 ## Basic Usage
@@ -13,42 +9,17 @@ These get automatically converted to a `<CodeBlock>`.
 alert('Hello World!');
 ```
 
-## Necessity of using `<script>` tags
-
-Whenever the content you place in a `<CodeBlock>`,
-includes characters that are used by HTML, you must
-wrap the content inside the `<CodeBlock>` in
-`<script>` tags, stating that this is literal data.
-
-<CodeBlock>
-<script>
-alert('Hello World!');
-</script>
-</CodeBlock>
-
-```html
-<CodeBlock>
-<script>
-alert('Hello World!');
-</script>
-</CodeBlock>
-```
-
 ## Documenting Components
 
 As any other code, components can be documented using the `<CodeBlock>`, too.
 
 <CodeBlock>
-<script>
-<Color color="#001dff">Blue</Color>
-</script>
+	<Color color="#001dff">Blue</Color>
 </CodeBlock>
 
 ```html
 <CodeBlock>
-<script>
-<Color color="#001dff">Blue</Color>
-</script>
+	<Color color="#001dff">Blue</Color>
 </CodeBlock>
 ```
 
@@ -64,9 +35,7 @@ alert("highlight this code");
 
 ```html
 <CodeBlock language="js">
-<script>
-alert("highlight this code");
-</script>
+	alert("highlight this code");
 </CodeBlock>
 ```
 
@@ -77,20 +46,16 @@ what the contents of a file called `fib.js` look like. To add a title you can
 set the `title` property of the `<CodeBlock>` component:
 
 <CodeBlock title="fib.js" language="js">
-<script>
 function fib(n) {
   return n < 2 ? n : fib(n - 1) + fib(n - 2);
 }
-</script>
 </CodeBlock>
 
 ```html
 <CodeBlock title="fib.js" language="js">
-<script>
 function fib(n) {
   return n < 2 ? n : fib(n - 1) + fib(n - 2);
 }
-</script>
 </CodeBlock>
 ```
 
@@ -100,4 +65,4 @@ A `<CodeBlock>` component can also load and display the content of a file stored
 
 ```html
 <CodeBlock src="data.json"></CodeBlock>
-```
+```

10_The Design Definitions Tree/02_Documents/10_Components/04-Inline Color/01-Readme.md

@@ -1,7 +1,3 @@
-<Banner title="Version Feature">
-  This Documentation component is available since version 1.3.
-</Banner>
-
 # Examples
 
 Colors can be used inline as well, for example this beautful shade of <Color color="#EE2222">Red</Color> is just gorgeous!

10_The Design Definitions Tree/02_Documents/10_Components/07-Do and Don’t/01-Readme.md

@@ -1,7 +1,3 @@
-<Banner title="Version Feature">
-  Documentation components are available since version 1.2.
-</Banner>
-
 # Example
 
 <DoDontGroup>

10_The Design Definitions Tree/02_Documents/10_Components/09-Code Embeds/01-Readme.md

@@ -1,7 +1,3 @@
-<Banner title="Version Feature">
-  Documentation components are available since version 1.3.
-</Banner>
-
 ## Glitch
 
 <Glitch id="hello-tensorflow"></Glitch>

10_The Design Definitions Tree/06_Versioning/Readme.md

@@ -1,9 +1,5 @@
 # Versioning
 
-<Banner title="Version Feature">
-  Support for versioning has been added in version 1.3.
-</Banner>
-
 Your Design Defintions Tree can be just any regular directory, but after a certain point it often makes sense to keep it in a [Git repository](https://git-scm.com/). This lets multiple authors collaborate in a more structured fashion, but it also comes with an added benefit: using Git you can have DSK display multiple versions of your design system. This is a powerful feature in larger organisations, were different products might have been built with different versions of the design system.
 
 When you keep your design system in a Git repository, all you have to do is [create a tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) for the version you want to expose and tell DSK about it by adding the tags name to the versions property of [DSK’s configuration file](/The-Design-Definitions-Tree/Configuration). The built-in frontend will now display a dropdown with all your versions in the lower left-hand corner and lets users select which one to look at.