From a3e4d29930fe0f906bb4845aa55032beae158159 Mon Sep 17 00:00:00 2001 From: Pascal Wilbrink Date: Mon, 12 Feb 2024 15:32:36 +0100 Subject: [PATCH] Feat: Update CSS --- _config.yml | 6 +- _includes/head.html | 1 - _layouts/guide.html | 9 +- _plugins/reading_time_filter.rb | 55 ++++++ assets/css/_syntax.scss | 261 +++++++++++++++++++++++++++ assets/css/components.css | 4 +- assets/css/components/card.css | 46 +++++ assets/css/components/toc.css | 34 ++++ assets/css/github-markdown.css | 2 +- assets/css/layout.css | 17 ++ assets/css/main.css | 9 +- assets/css/pages.css | 3 + assets/css/syntax.css | 70 +++++++ assets/sass/_syntax.scss | 261 +++++++++++++++++++++++++++ collections/_guides/create_plugin.md | 232 ++++++++++++++++++++++++ docker-compose.yml | 2 +- index.html | 4 +- pages/glossary.md | 1 + pages/guides.md | 26 +-- 19 files changed, 1017 insertions(+), 26 deletions(-) create mode 100644 _plugins/reading_time_filter.rb create mode 100644 assets/css/_syntax.scss create mode 100644 assets/css/components/card.css create mode 100644 assets/css/components/toc.css create mode 100644 assets/css/syntax.css create mode 100644 assets/sass/_syntax.scss create mode 100644 collections/_guides/create_plugin.md diff --git a/_config.yml b/_config.yml index 78764c5..bc1cd35 100644 --- a/_config.yml +++ b/_config.yml @@ -11,8 +11,8 @@ description: > # this means to ignore newlines until "baseurl:" Write an awesome description for your new site here. You can edit this line in _config.yml. It will appear in your document head meta (for Google search results) and in your feed.xml site description. -baseurl: "/Documentation" # the subpath of your site, e.g. /blog -url: "https://openscd.github.io" # the base hostname & protocol for your site +#baseurl: "/Documentation" # the subpath of your site, e.g. /blog +#url: "https://openscd.github.io" # the base hostname & protocol for your site collections_dir: collections # Markdown settings @@ -27,7 +27,7 @@ toc: ordered_list: false no_toc_section_class: no_toc_section list_id: toc - list_class: section-nav + list_class: nav--toc sublist_class: '' item_class: toc-entry item_prefix: toc- diff --git a/_includes/head.html b/_includes/head.html index 0b7f0cb..ed5cfc6 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -2,7 +2,6 @@ - {% if page.title %}{{ page.title | escape }}{% else %}{{ site.title | escape }}{% endif %} diff --git a/_layouts/guide.html b/_layouts/guide.html index 233f935..f8393a9 100644 --- a/_layouts/guide.html +++ b/_layouts/guide.html @@ -20,18 +20,21 @@ {% include header.html %} -
+
+
+ {{ page.summary }} +
- {{ page.content }} + {{ page.content | inject_anchors }}
diff --git a/_plugins/reading_time_filter.rb b/_plugins/reading_time_filter.rb new file mode 100644 index 0000000..a740a8e --- /dev/null +++ b/_plugins/reading_time_filter.rb @@ -0,0 +1,55 @@ +module ReadingTimeFilter + include Liquid::StandardFilters + + def reading_time(input) + # Get words count. + total_words = get_plain_text(input).split.size + + # Load configuration. + config = @context.registers[:site].config["reading_time"] + + # Setup default value. + if ! config + second_plural = "seconds" + minute_singular = "minute" + minute_plural = "minutes" + else + second_plural = config["second_plural"] ? config["second_plural"] : "seconds" + minute_singular = config["minute_singular"] ? config["minute_singular"] : "minute" + minute_plural = config["minute_plural"] ? config["minute_plural"] : "minutes" + end + + # Average reading words per minute. + words_per_minute = 180 + + # Calculate reading time. + case total_words + when 0 .. 89 + return "30 #{second_plural}" + when 90 .. 269 + return "1 #{minute_singular}" + when 270 .. 449 + return "2 #{minute_plural}" + when 450 .. 629 + return "3 #{minute_plural}" + when 630 .. 809 + return "4 #{minute_plural}" + when 810 .. 990 + return "5 #{minute_plural}" + else + minutes = ( total_words / words_per_minute ).floor + return "#{minutes} #{minute_plural}"; + end + end + + def get_plain_text(input) + strip_html(strip_pre_tags(input)) + end + + def strip_pre_tags(input) + empty = ''.freeze + input.to_s.gsub(//mi, empty) + end + end + + Liquid::Template.register_filter(ReadingTimeFilter) \ No newline at end of file diff --git a/assets/css/_syntax.scss b/assets/css/_syntax.scss new file mode 100644 index 0000000..f3f22a8 --- /dev/null +++ b/assets/css/_syntax.scss @@ -0,0 +1,261 @@ +.highlight, html .gist .gist-file .gist-syntax .gist-highlight { + table td.code { width: 100%; } + border: 1px solid $pre-border !important; + } + .highlight .line-numbers, html .gist .gist-file .gist-syntax .highlight .line_numbers { + text-align: right; + font-size: 13px; + line-height: 1.45em; + @if $solarized == light { + background: lighten($base03, 1) $noise-bg !important; + border-right: 1px solid darken($base02, 2) !important; + @include box-shadow(lighten($base03, 2) -1px 0 inset); + text-shadow: lighten($base02, 2) 0 -1px; + } @else { + background: $base02 $noise-bg !important; + border-right: 1px solid darken($base03, 2) !important; + @include box-shadow(lighten($base02, 2) -1px 0 inset); + text-shadow: darken($base02, 10) 0 -1px; + } + span { color: $base01 !important; } + padding: .8em !important; + @include border-radius(0); + } + + figure.code, .gist-file, pre { + @include box-shadow(rgba(#000, .06) 0 0 10px); + .highlight pre { @include box-shadow(none); } + } + + .gist .highlight, figure.code .highlight { + @include selection(adjust-color($base03, $lightness: 23%, $saturation: -65%), $text-shadow: $base03 0 1px); + } + html .gist .gist-file { + margin-bottom: 1.8em; + position: relative; + border: none; + padding-top: image-height("code_bg.png") !important; + .highlight { + margin-bottom: 0; + } + .gist-syntax { + border-bottom: 0 !important; + background: none !important; + .gist-highlight { + background: $base03 !important; + } + .highlight pre { + @extend .pre-code; + padding: 0; + } + } + .gist-meta { + padding: .6em 0.8em; + border: 1px solid lighten($base02, 2) !important; + color: $base01; + font-size: .7em !important; + @if $solarized == light { + background: lighten($base03, 2) $noise-bg; + border: 1px solid $pre-border !important; + border-top: 1px solid lighten($base03, 2) !important; + } @else { + background: $base02 $noise-bg; + } + @extend .sans; + line-height: 1.5em; + a { + color: mix($base1, $base01) !important; + @include hover-link; + &:hover { color: $base1 !important; } + } + a[href*='#file'] { + position: absolute; top: 0; left:0; right:-10px; + color: #474747 !important; + @extend .code-title; + &:hover { color: $link-color !important; } + } + a[href*=raw]{ + @extend .download-source; + top: .4em; + } + } + } + pre { + background: $pre-bg $noise-bg; + @include border-radius(.4em); + @extend .mono; + border: 1px solid $pre-border; + line-height: 1.45em; + font-size: 13px; + margin-bottom: 2.1em; + padding: .8em 1em; + color: $pre-color; + overflow: auto; + } + h3.filename { + @extend .code-title; + + pre { @include border-top-radius(0px); } + } + + p, li { + code { + @extend .mono; + display: inline-block; + white-space: no-wrap; + background: #fff; + font-size: .8em; + line-height: 1.5em; + color: #555; + border: 1px solid #ddd; + @include border-radius(.4em); + padding: 0 .3em; + margin: -1px 0; + } + pre code { font-size: 1em !important; background: none; border: none; } + } + + .pre-code { + font-family: $mono !important; + overflow: scroll; + overflow-y: hidden; + display: block; + padding: .8em; + overflow-x: auto; + line-height: 1.45em; + background: $base03 $noise-bg !important; + color: $base1 !important; + span { color: $base1 !important; } + span { font-style: normal !important; font-weight: normal !important; } + + .c { color: $base01 !important; font-style: italic !important; } /* Comment */ + .cm { color: $base01 !important; font-style: italic !important; } /* Comment.Multiline */ + .cp { color: $base01 !important; font-style: italic !important; } /* Comment.Preproc */ + .c1 { color: $base01 !important; font-style: italic !important; } /* Comment.Single */ + .cs { color: $base01 !important; font-weight: bold !important; font-style: italic !important; } /* Comment.Special */ + .err { color: $solar-red !important; background: none !important; } /* Error */ + .k { color: $solar-orange !important; } /* Keyword */ + .o { color: $base1 !important; font-weight: bold !important; } /* Operator */ + .p { color: $base1 !important; } /* Operator */ + .ow { color: $solar-cyan !important; font-weight: bold !important; } /* Operator.Word */ + .gd { color: $base1 !important; background-color: mix($solar-red, $base03, 25%) !important; display: inline-block; } /* Generic.Deleted */ + .gd .x { color: $base1 !important; background-color: mix($solar-red, $base03, 35%) !important; display: inline-block; } /* Generic.Deleted.Specific */ + .ge { color: $base1 !important; font-style: italic !important; } /* Generic.Emph */ + //.gr { color: #aa0000 } /* Generic.Error */ + .gh { color: $base01 !important; } /* Generic.Heading */ + .gi { color: $base1 !important; background-color: mix($solar-green, $base03, 20%) !important; display: inline-block; } /* Generic.Inserted */ + .gi .x { color: $base1 !important; background-color: mix($solar-green, $base03, 40%) !important; display: inline-block; } /* Generic.Inserted.Specific */ + //.go { color: #888888 } /* Generic.Output */ + //.gp { color: #555555 } /* Generic.Prompt */ + .gs { color: $base1 !important; font-weight: bold !important; } /* Generic.Strong */ + .gu { color: $solar-violet !important; } /* Generic.Subheading */ + //.gt { color: #aa0000 } /* Generic.Traceback */ + .kc { color: $solar-green !important; font-weight: bold !important; } /* Keyword.Constant */ + .kd { color: $solar-blue !important; } /* Keyword.Declaration */ + .kp { color: $solar-orange !important; font-weight: bold !important; } /* Keyword.Pseudo */ + .kr { color: $solar-magenta !important; font-weight: bold !important; } /* Keyword.Reserved */ + .kt { color: $solar-cyan !important; } /* Keyword.Type */ + .n { color: $solar-blue !important; } + .na { color: $solar-blue !important; } /* Name.Attribute */ + .nb { color: $solar-green !important; } /* Name.Builtin */ + .nc { color: $solar-magenta !important;} /* Name.Class */ + .no { color: $solar-yellow !important; } /* Name.Constant */ + //.ni { color: #800080 } /* Name.Entity */ + .nl { color: $solar-green !important; } + .ne { color: $solar-blue !important; font-weight: bold !important; } /* Name.Exception */ + .nf { color: $solar-blue !important; font-weight: bold !important; } /* Name.Function */ + .nn { color: $solar-yellow !important; } /* Name.Namespace */ + .nt { color: $solar-blue !important; font-weight: bold !important; } /* Name.Tag */ + .nx { color: $solar-yellow !Important; } + //.bp { color: #999999 } /* Name.Builtin.Pseudo */ + //.vc { color: #008080 } /* Name.Variable.Class */ + .vg { color: $solar-blue !important; } /* Name.Variable.Global */ + .vi { color: $solar-blue !important; } /* Name.Variable.Instance */ + .nv { color: $solar-blue !important; } /* Name.Variable */ + //.w { color: #bbbbbb } /* Text.Whitespace */ + .mf { color: $solar-cyan !important; } /* Literal.Number.Float */ + .m { color: $solar-cyan !important; } /* Literal.Number */ + .mh { color: $solar-cyan !important; } /* Literal.Number.Hex */ + .mi { color: $solar-cyan !important; } /* Literal.Number.Integer */ + //.mo { color: #009999 } /* Literal.Number.Oct */ + .s { color: $solar-cyan !important; } /* Literal.String */ + //.sb { color: #d14 } /* Literal.String.Backtick */ + //.sc { color: #d14 } /* Literal.String.Char */ + .sd { color: $solar-cyan !important; } /* Literal.String.Doc */ + .s2 { color: $solar-cyan !important; } /* Literal.String.Double */ + .se { color: $solar-red !important; } /* Literal.String.Escape */ + //.sh { color: #d14 } /* Literal.String.Heredoc */ + .si { color: $solar-blue !important; } /* Literal.String.Interpol */ + //.sx { color: #d14 } /* Literal.String.Other */ + .sr { color: $solar-cyan !important; } /* Literal.String.Regex */ + .s1 { color: $solar-cyan !important; } /* Literal.String.Single */ + //.ss { color: #990073 } /* Literal.String.Symbol */ + //.il { color: #009999 } /* Literal.Number.Integer.Long */ + div { .gd, .gd .x, .gi, .gi .x { display: inline-block; width: 100%; }} + } + + .highlight, .gist-highlight { + pre { background: none; @include border-radius(0px); border: none; padding: 0; margin-bottom: 0; } + margin-bottom: 1.8em; + background: $base03; + overflow-y: hidden; + overflow-x: auto; + } + + $solar-scroll-bg: rgba(#fff, .15); + $solar-scroll-thumb: rgba(#fff, .2); + @if $solarized == light { + $solar-scroll-bg: rgba(#000, .15); + $solar-scroll-thumb: rgba(#000, .15); + } + + pre, .highlight, .gist-highlight { + &::-webkit-scrollbar { height: .5em; background: $solar-scroll-bg; } + &::-webkit-scrollbar-thumb:horizontal { background: $solar-scroll-thumb; -webkit-border-radius: 4px; border-radius: 4px } + } + + .highlight code { + @extend .pre-code; background: #000; + } + figure.code { + background: none; + padding: 0; + border: 0; + margin-bottom: 1.5em; + pre { margin-bottom: 0; } + figcaption { + position: relative; + @extend .code-title; + a { @extend .download-source; } + } + .highlight { + margin-bottom: 0; + } + } + + .code-title { + text-align: center; + font-size: 13px; + line-height: 2em; + text-shadow: #cbcccc 0 1px 0; + color: #474747; + font-weight: normal; + margin-bottom: 0; + @include border-top-radius(5px); + font-family: "Helvetica Neue", Arial, "Lucida Grande", "Lucida Sans Unicode", Lucida, sans-serif; + background: #aaaaaa image-url("code_bg.png") top repeat-x; + border: 1px solid #565656; + border-top-color: #cbcbcb; + border-left-color: #a5a5a5; + border-right-color: #a5a5a5; + border-bottom: 0; + } + + .download-source { + position: absolute; right: .8em; + @include hover-link; + color: #666 !important; + z-index: 1; + font-size: 13px; + text-shadow: #cbcccc 0 1px 0; + padding-left: 3em; + } \ No newline at end of file diff --git a/assets/css/components.css b/assets/css/components.css index ef80581..67cf95e 100644 --- a/assets/css/components.css +++ b/assets/css/components.css @@ -1,3 +1,5 @@ @import 'components/header.css'; @import 'components/hero.css'; -@import 'components/button.css'; \ No newline at end of file +@import 'components/button.css'; +@import 'components/card.css'; +@import 'components/toc.css'; \ No newline at end of file diff --git a/assets/css/components/card.css b/assets/css/components/card.css new file mode 100644 index 0000000..38c161c --- /dev/null +++ b/assets/css/components/card.css @@ -0,0 +1,46 @@ +.card { + border-radius: 5px; + border: 1px solid #DADADA; + padding: 16px; + margin-bottom: 32px; + background: #FFFFFF; + display: block; + color: #000000; + text-decoration: none; +} + +.card--selectable { + transition: all 230ms ease-in-out; +} + +.card--selectable:hover { + box-shadow: 0 1px 3px rgba(0, 0, 0, .07), + 0 2px 5px rgba(0, 0, 0, .09), + 0 4px 8px rgba(0, 0, 0, .11); + cursor: pointer; + transition: all 230ms ease-in-out; +} + +.card__header { + color: #000000; + font-weight: 600; + font-size: 1.4em; + margin-bottom: 8px; +} + +.card__header > a { + color: inherit; + text-decoration: none; +} + +.card__sub-header { + display: flex; + align-items: center; + gap: 16px; + margin-bottom: 8px; +} + +.card__sub-header > span { + display: flex; + gap: 4px; +} \ No newline at end of file diff --git a/assets/css/components/toc.css b/assets/css/components/toc.css new file mode 100644 index 0000000..0d8cf7f --- /dev/null +++ b/assets/css/components/toc.css @@ -0,0 +1,34 @@ +.nav--toc { + list-style-type: none; + margin: 0; + padding: 0; +} + +.nav--toc a { + color: var(--primary-color); +} + +.toc-entry { + font-weight: 500; + margin-bottom: 4px; + position: relative; +} + +.toc-entry::before { + content: ''; + position: absolute; + left: 0; + bottom: 0; + width: 0; + border-bottom: 2px solid var(--primary-color); + transition: all 230ms ease-in-out; +} + +.toc-entry a { + text-decoration: none; +} + +.toc-entry:hover::before { + width: 100%; + transition: all 230ms ease-in-out; +} diff --git a/assets/css/github-markdown.css b/assets/css/github-markdown.css index d32a314..e3895f1 100644 --- a/assets/css/github-markdown.css +++ b/assets/css/github-markdown.css @@ -94,7 +94,7 @@ --color-fg-muted: #656d76; --color-fg-subtle: #6e7781; --color-canvas-default: #ffffff; - --color-canvas-subtle: #f6f8fa; + --color-canvas-subtle: rgb(51, 51, 51); --color-border-default: #d0d7de; --color-border-muted: hsla(210,18%,87%,1); --color-neutral-muted: rgba(175,184,193,0.2); diff --git a/assets/css/layout.css b/assets/css/layout.css index a1f2830..e3a34f3 100644 --- a/assets/css/layout.css +++ b/assets/css/layout.css @@ -10,4 +10,21 @@ .flex { flex: 1; display: block; +} + +.content { + margin: 32px 64px; +} + +.content--sidebar { + display: flex; + gap: 32px; +} + +.content aside { + width: 320px; +} + +.main { + flex: 1; } \ No newline at end of file diff --git a/assets/css/main.css b/assets/css/main.css index 397f28b..19c091e 100644 --- a/assets/css/main.css +++ b/assets/css/main.css @@ -1,9 +1,11 @@ @import url('https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;800&display=swap'); @import 'components.css'; @import 'layout.css'; +@import 'pages.css'; :root { --primary-color: #29639f; + --color-canvas-subtle: rgb(51, 51, 51); } html, @@ -11,7 +13,11 @@ body { margin: 0; padding: 0; width: 100%; - height: 100vh; + height: 100%; +} + +body { + background: #F8F6F4; } * { @@ -33,7 +39,6 @@ body { color: #FFFFFF; } - .contact__container { display: flex; align-items: center; diff --git a/assets/css/pages.css b/assets/css/pages.css index e69de29..815dad9 100644 --- a/assets/css/pages.css +++ b/assets/css/pages.css @@ -0,0 +1,3 @@ +.guides { + flex: 1; +} \ No newline at end of file diff --git a/assets/css/syntax.css b/assets/css/syntax.css new file mode 100644 index 0000000..a96be73 --- /dev/null +++ b/assets/css/syntax.css @@ -0,0 +1,70 @@ +.highlight pre { background-color: #333; } +.highlight .hll { background-color: #333333 } +.highlight .c { color: #008800; font-style: italic; background-color: #0f140f } /* Comment */ +.highlight .err { color: #ffffff } /* Error */ +.highlight .g { color: #ffffff } /* Generic */ +.highlight .k { color: #fb660a; font-weight: bold } /* Keyword */ +.highlight .l { color: #ffffff } /* Literal */ +.highlight .n { color: #ffffff } /* Name */ +.highlight .o { color: #ffffff } /* Operator */ +.highlight .x { color: #ffffff } /* Other */ +.highlight .p { color: #ffffff } /* Punctuation */ +.highlight .cm { color: #008800; font-style: italic; background-color: #0f140f } /* Comment.Multiline */ +.highlight .cp { color: #ff0007; font-weight: bold; font-style: italic; background-color: #0f140f } /* Comment.Preproc */ +.highlight .c1 { color: #008800; font-style: italic; background-color: #0f140f } /* Comment.Single */ +.highlight .cs { color: #008800; font-style: italic; background-color: #0f140f } /* Comment.Special */ +.highlight .gd { color: #ffffff } /* Generic.Deleted */ +.highlight .ge { color: #ffffff } /* Generic.Emph */ +.highlight .gr { color: #ffffff } /* Generic.Error */ +.highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #ffffff } /* Generic.Inserted */ +.highlight .go { color: #444444; background-color: #222222 } /* Generic.Output */ +.highlight .gp { color: #ffffff } /* Generic.Prompt */ +.highlight .gs { color: #ffffff } /* Generic.Strong */ +.highlight .gu { color: #ffffff; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #ffffff } /* Generic.Traceback */ +.highlight .kc { color: #fb660a; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #fb660a; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #fb660a; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #fb660a } /* Keyword.Pseudo */ +.highlight .kr { color: #fb660a; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #cdcaa9; font-weight: bold } /* Keyword.Type */ +.highlight .ld { color: #ffffff } /* Literal.Date */ +.highlight .m { color: #0086f7; font-weight: bold } /* Literal.Number */ +.highlight .s { color: #0086d2 } /* Literal.String */ +.highlight .na { color: #ff0086; font-weight: bold } /* Name.Attribute */ +.highlight .nb { color: #ffffff } /* Name.Builtin */ +.highlight .nc { color: #ffffff } /* Name.Class */ +.highlight .no { color: #0086d2 } /* Name.Constant */ +.highlight .nd { color: #ffffff } /* Name.Decorator */ +.highlight .ni { color: #ffffff } /* Name.Entity */ +.highlight .ne { color: #ffffff } /* Name.Exception */ +.highlight .nf { color: #ff0086; font-weight: bold } /* Name.Function */ +.highlight .nl { color: #ffffff } /* Name.Label */ +.highlight .nn { color: #ffffff } /* Name.Namespace */ +.highlight .nx { color: #ffffff } /* Name.Other */ +.highlight .py { color: #ffffff } /* Name.Property */ +.highlight .nt { color: #fb660a; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #fb660a } /* Name.Variable */ +.highlight .ow { color: #ffffff } /* Operator.Word */ +.highlight .w { color: #888888 } /* Text.Whitespace */ +.highlight .mf { color: #0086f7; font-weight: bold } /* Literal.Number.Float */ +.highlight .mh { color: #0086f7; font-weight: bold } /* Literal.Number.Hex */ +.highlight .mi { color: #0086f7; font-weight: bold } /* Literal.Number.Integer */ +.highlight .mo { color: #0086f7; font-weight: bold } /* Literal.Number.Oct */ +.highlight .sb { color: #0086d2 } /* Literal.String.Backtick */ +.highlight .sc { color: #0086d2 } /* Literal.String.Char */ +.highlight .sd { color: #0086d2 } /* Literal.String.Doc */ +.highlight .s2 { color: #0086d2 } /* Literal.String.Double */ +.highlight .se { color: #0086d2 } /* Literal.String.Escape */ +.highlight .sh { color: #0086d2 } /* Literal.String.Heredoc */ +.highlight .si { color: #0086d2 } /* Literal.String.Interpol */ +.highlight .sx { color: #0086d2 } /* Literal.String.Other */ +.highlight .sr { color: #0086d2 } /* Literal.String.Regex */ +.highlight .s1 { color: #0086d2 } /* Literal.String.Single */ +.highlight .ss { color: #0086d2 } /* Literal.String.Symbol */ +.highlight .bp { color: #ffffff } /* Name.Builtin.Pseudo */ +.highlight .vc { color: #fb660a } /* Name.Variable.Class */ +.highlight .vg { color: #fb660a } /* Name.Variable.Global */ +.highlight .vi { color: #fb660a } /* Name.Variable.Instance */ +.highlight .il { color: #0086f7; font-weight: bold } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/assets/sass/_syntax.scss b/assets/sass/_syntax.scss new file mode 100644 index 0000000..f3f22a8 --- /dev/null +++ b/assets/sass/_syntax.scss @@ -0,0 +1,261 @@ +.highlight, html .gist .gist-file .gist-syntax .gist-highlight { + table td.code { width: 100%; } + border: 1px solid $pre-border !important; + } + .highlight .line-numbers, html .gist .gist-file .gist-syntax .highlight .line_numbers { + text-align: right; + font-size: 13px; + line-height: 1.45em; + @if $solarized == light { + background: lighten($base03, 1) $noise-bg !important; + border-right: 1px solid darken($base02, 2) !important; + @include box-shadow(lighten($base03, 2) -1px 0 inset); + text-shadow: lighten($base02, 2) 0 -1px; + } @else { + background: $base02 $noise-bg !important; + border-right: 1px solid darken($base03, 2) !important; + @include box-shadow(lighten($base02, 2) -1px 0 inset); + text-shadow: darken($base02, 10) 0 -1px; + } + span { color: $base01 !important; } + padding: .8em !important; + @include border-radius(0); + } + + figure.code, .gist-file, pre { + @include box-shadow(rgba(#000, .06) 0 0 10px); + .highlight pre { @include box-shadow(none); } + } + + .gist .highlight, figure.code .highlight { + @include selection(adjust-color($base03, $lightness: 23%, $saturation: -65%), $text-shadow: $base03 0 1px); + } + html .gist .gist-file { + margin-bottom: 1.8em; + position: relative; + border: none; + padding-top: image-height("code_bg.png") !important; + .highlight { + margin-bottom: 0; + } + .gist-syntax { + border-bottom: 0 !important; + background: none !important; + .gist-highlight { + background: $base03 !important; + } + .highlight pre { + @extend .pre-code; + padding: 0; + } + } + .gist-meta { + padding: .6em 0.8em; + border: 1px solid lighten($base02, 2) !important; + color: $base01; + font-size: .7em !important; + @if $solarized == light { + background: lighten($base03, 2) $noise-bg; + border: 1px solid $pre-border !important; + border-top: 1px solid lighten($base03, 2) !important; + } @else { + background: $base02 $noise-bg; + } + @extend .sans; + line-height: 1.5em; + a { + color: mix($base1, $base01) !important; + @include hover-link; + &:hover { color: $base1 !important; } + } + a[href*='#file'] { + position: absolute; top: 0; left:0; right:-10px; + color: #474747 !important; + @extend .code-title; + &:hover { color: $link-color !important; } + } + a[href*=raw]{ + @extend .download-source; + top: .4em; + } + } + } + pre { + background: $pre-bg $noise-bg; + @include border-radius(.4em); + @extend .mono; + border: 1px solid $pre-border; + line-height: 1.45em; + font-size: 13px; + margin-bottom: 2.1em; + padding: .8em 1em; + color: $pre-color; + overflow: auto; + } + h3.filename { + @extend .code-title; + + pre { @include border-top-radius(0px); } + } + + p, li { + code { + @extend .mono; + display: inline-block; + white-space: no-wrap; + background: #fff; + font-size: .8em; + line-height: 1.5em; + color: #555; + border: 1px solid #ddd; + @include border-radius(.4em); + padding: 0 .3em; + margin: -1px 0; + } + pre code { font-size: 1em !important; background: none; border: none; } + } + + .pre-code { + font-family: $mono !important; + overflow: scroll; + overflow-y: hidden; + display: block; + padding: .8em; + overflow-x: auto; + line-height: 1.45em; + background: $base03 $noise-bg !important; + color: $base1 !important; + span { color: $base1 !important; } + span { font-style: normal !important; font-weight: normal !important; } + + .c { color: $base01 !important; font-style: italic !important; } /* Comment */ + .cm { color: $base01 !important; font-style: italic !important; } /* Comment.Multiline */ + .cp { color: $base01 !important; font-style: italic !important; } /* Comment.Preproc */ + .c1 { color: $base01 !important; font-style: italic !important; } /* Comment.Single */ + .cs { color: $base01 !important; font-weight: bold !important; font-style: italic !important; } /* Comment.Special */ + .err { color: $solar-red !important; background: none !important; } /* Error */ + .k { color: $solar-orange !important; } /* Keyword */ + .o { color: $base1 !important; font-weight: bold !important; } /* Operator */ + .p { color: $base1 !important; } /* Operator */ + .ow { color: $solar-cyan !important; font-weight: bold !important; } /* Operator.Word */ + .gd { color: $base1 !important; background-color: mix($solar-red, $base03, 25%) !important; display: inline-block; } /* Generic.Deleted */ + .gd .x { color: $base1 !important; background-color: mix($solar-red, $base03, 35%) !important; display: inline-block; } /* Generic.Deleted.Specific */ + .ge { color: $base1 !important; font-style: italic !important; } /* Generic.Emph */ + //.gr { color: #aa0000 } /* Generic.Error */ + .gh { color: $base01 !important; } /* Generic.Heading */ + .gi { color: $base1 !important; background-color: mix($solar-green, $base03, 20%) !important; display: inline-block; } /* Generic.Inserted */ + .gi .x { color: $base1 !important; background-color: mix($solar-green, $base03, 40%) !important; display: inline-block; } /* Generic.Inserted.Specific */ + //.go { color: #888888 } /* Generic.Output */ + //.gp { color: #555555 } /* Generic.Prompt */ + .gs { color: $base1 !important; font-weight: bold !important; } /* Generic.Strong */ + .gu { color: $solar-violet !important; } /* Generic.Subheading */ + //.gt { color: #aa0000 } /* Generic.Traceback */ + .kc { color: $solar-green !important; font-weight: bold !important; } /* Keyword.Constant */ + .kd { color: $solar-blue !important; } /* Keyword.Declaration */ + .kp { color: $solar-orange !important; font-weight: bold !important; } /* Keyword.Pseudo */ + .kr { color: $solar-magenta !important; font-weight: bold !important; } /* Keyword.Reserved */ + .kt { color: $solar-cyan !important; } /* Keyword.Type */ + .n { color: $solar-blue !important; } + .na { color: $solar-blue !important; } /* Name.Attribute */ + .nb { color: $solar-green !important; } /* Name.Builtin */ + .nc { color: $solar-magenta !important;} /* Name.Class */ + .no { color: $solar-yellow !important; } /* Name.Constant */ + //.ni { color: #800080 } /* Name.Entity */ + .nl { color: $solar-green !important; } + .ne { color: $solar-blue !important; font-weight: bold !important; } /* Name.Exception */ + .nf { color: $solar-blue !important; font-weight: bold !important; } /* Name.Function */ + .nn { color: $solar-yellow !important; } /* Name.Namespace */ + .nt { color: $solar-blue !important; font-weight: bold !important; } /* Name.Tag */ + .nx { color: $solar-yellow !Important; } + //.bp { color: #999999 } /* Name.Builtin.Pseudo */ + //.vc { color: #008080 } /* Name.Variable.Class */ + .vg { color: $solar-blue !important; } /* Name.Variable.Global */ + .vi { color: $solar-blue !important; } /* Name.Variable.Instance */ + .nv { color: $solar-blue !important; } /* Name.Variable */ + //.w { color: #bbbbbb } /* Text.Whitespace */ + .mf { color: $solar-cyan !important; } /* Literal.Number.Float */ + .m { color: $solar-cyan !important; } /* Literal.Number */ + .mh { color: $solar-cyan !important; } /* Literal.Number.Hex */ + .mi { color: $solar-cyan !important; } /* Literal.Number.Integer */ + //.mo { color: #009999 } /* Literal.Number.Oct */ + .s { color: $solar-cyan !important; } /* Literal.String */ + //.sb { color: #d14 } /* Literal.String.Backtick */ + //.sc { color: #d14 } /* Literal.String.Char */ + .sd { color: $solar-cyan !important; } /* Literal.String.Doc */ + .s2 { color: $solar-cyan !important; } /* Literal.String.Double */ + .se { color: $solar-red !important; } /* Literal.String.Escape */ + //.sh { color: #d14 } /* Literal.String.Heredoc */ + .si { color: $solar-blue !important; } /* Literal.String.Interpol */ + //.sx { color: #d14 } /* Literal.String.Other */ + .sr { color: $solar-cyan !important; } /* Literal.String.Regex */ + .s1 { color: $solar-cyan !important; } /* Literal.String.Single */ + //.ss { color: #990073 } /* Literal.String.Symbol */ + //.il { color: #009999 } /* Literal.Number.Integer.Long */ + div { .gd, .gd .x, .gi, .gi .x { display: inline-block; width: 100%; }} + } + + .highlight, .gist-highlight { + pre { background: none; @include border-radius(0px); border: none; padding: 0; margin-bottom: 0; } + margin-bottom: 1.8em; + background: $base03; + overflow-y: hidden; + overflow-x: auto; + } + + $solar-scroll-bg: rgba(#fff, .15); + $solar-scroll-thumb: rgba(#fff, .2); + @if $solarized == light { + $solar-scroll-bg: rgba(#000, .15); + $solar-scroll-thumb: rgba(#000, .15); + } + + pre, .highlight, .gist-highlight { + &::-webkit-scrollbar { height: .5em; background: $solar-scroll-bg; } + &::-webkit-scrollbar-thumb:horizontal { background: $solar-scroll-thumb; -webkit-border-radius: 4px; border-radius: 4px } + } + + .highlight code { + @extend .pre-code; background: #000; + } + figure.code { + background: none; + padding: 0; + border: 0; + margin-bottom: 1.5em; + pre { margin-bottom: 0; } + figcaption { + position: relative; + @extend .code-title; + a { @extend .download-source; } + } + .highlight { + margin-bottom: 0; + } + } + + .code-title { + text-align: center; + font-size: 13px; + line-height: 2em; + text-shadow: #cbcccc 0 1px 0; + color: #474747; + font-weight: normal; + margin-bottom: 0; + @include border-top-radius(5px); + font-family: "Helvetica Neue", Arial, "Lucida Grande", "Lucida Sans Unicode", Lucida, sans-serif; + background: #aaaaaa image-url("code_bg.png") top repeat-x; + border: 1px solid #565656; + border-top-color: #cbcbcb; + border-left-color: #a5a5a5; + border-right-color: #a5a5a5; + border-bottom: 0; + } + + .download-source { + position: absolute; right: .8em; + @include hover-link; + color: #666 !important; + z-index: 1; + font-size: 13px; + text-shadow: #cbcccc 0 1px 0; + padding-left: 3em; + } \ No newline at end of file diff --git a/collections/_guides/create_plugin.md b/collections/_guides/create_plugin.md new file mode 100644 index 0000000..b408f41 --- /dev/null +++ b/collections/_guides/create_plugin.md @@ -0,0 +1,232 @@ +--- +difficulty: 2 +summary: Create a plugin for OpenSCD in just a couple of steps +title: How to write a plugin for OpenSCD +toc: true +layout: guide +cover: solar +--- + + +This tutorial will explain on how to write a plugin for OpenSCD. + +## Prerequisites +* Node ( LTS) +* Git +* An IDE + +In this example, we will use the Lit framework ([https://lit.dev](https://lit.dev)) to create a plugin for OpenSCD. On top of the Lit framework, we make use of the standards provided by Open Web Components ([open-wc.org](https://open-wc.org/)). + + +# Scaffolding a new plugin +We can scaffold a new empty project by using the `@open-wc` init command. + +{% highlight ts %} +npm init @open-wc +{% endhighlight %} + +--- + +When prompted, choose the following: + +`What would you like to do today?` › Scaffold a new project + +`What would you like to scaffold?` › Web Component + +`What would you like to add?` › Linting (eslint & prettier), Testing (web-test-runner), Demoing (storybook) + +`Would you like to use typescript?` › Yes + +`What is the tag name of your web component?` › oscd-my-new-plugin + +--- + +After scaffolding is complete, the first thing that we need to do is to change the plugin class. + +Open the `OscdMyNewPlugin.ts` file in the `src` folder and change the following line: + +{% highlight ts %} +- export class OscdMyNewPlugin extends LitElement { ++ export default class OscdMyNewPlugin extends LitElement { +{% endhighlight %} + +> Note the `default` keyword. + +--- + +Now, the `src/oscd-my-new-plugin.ts` file needs to be changed: + +{% highlight ts %} +- import { OscdMyNewPlugin } from './OscdMyNewPlugin.js'; ++ import OscdMyNewPlugin from './OscdMyNewPlugin.js'; +{% endhighlight %} + +> Note the removed brackets + +--- + +The last thing we have to change, is the `src/index.ts` file. + +{% highlight ts %} +- export { OscdMyNewPlugin } from './OscdMyNewPlugin.js'; ++ export * from './OscdMyNewPlugin.js'; +{% endhighlight %} + +> Note the asterisk on export + +--- + +This change is making sure that the plugin is default exported, so that OpenSCD can dynamically import it correctly. + +# Setting up property injection +In order to start displaying or editing the SCL file, we first need to add properties that will be injected into the plugin. + +Inside the `OscdMyNewPlugin.ts` file, add the following code: + +{% highlight ts %} +import { html, css, LitElement } from 'lit'; +import { property } from 'lit/decorators.js'; + +export default class OscdMyNewPlugin extends LitElement { + + @property({ type: Object }) + doc!: XMLDocument; + + @property({ type: Number }) + editCount = -1; + + @property({ type: String }) + locale!: string; + + ... +{% endhighlight %} + +These properties will be injected into the Plugin from the OpenSCD host. + +# Choosing the Plugin type +OpenSCD currently supports 2 different plugin types. +* Menu type plugins +* Editor type plugins + +## Menu type plugins +--- +Menu type plugins usually run on the background. They are displayed in the sidebar menu and are rendered at all times. +Example of menu type plugins are: +* Validators +* Generators + +## Editor type plugins +--- +Editor type plugins are displayed in the main Editor. An editor type plugin will be rendered when it's being activated by the Tab bar on top of OpenSCD. +Examples of editor type plugins are: +* Communication editor +* Substation editor +* Single Line Diagram + +If you choose to make your plugin a Menu type plugin, you need to implement the `run` method in your plugin. + +{% highlight ts %} +import { html, css, LitElement } from 'lit'; +import { property } from 'lit/decorators.js'; + +export default class OscdMyNewPlugin extends LitElement { + + @property({ type: Object }) + doc!: XMLDocument; + + @property({ type: Number }) + editCount = -1; + + @property({ type: String }) + locale!: string; + + async run(): Promise { + ... Plugin implementation goes here + } + +{% endhighlight %} + +If you choose to make your plugin an Editor type plugin, you need to implement the `render` function from Lit. + +{% highlight ts %} +import { html, css, LitElement, TemplateResult } from 'lit'; +import { property } from 'lit/decorators.js'; + +export default class OscdMyNewPlugin extends LitElement { + + @property({ type: Object }) + doc!: XMLDocument; + + @property({ type: Number }) + editCount = -1; + + @property({ type: String }) + locale!: string; + + render(): TemplateResult { + return html`
My plugin works!
`; + } +{% endhighlight %} + +In this example, we'll choose for an editor type plugin. + +# Adding functionality to the plugin + +The SCL document can be traversed like any other HTMLElement. +Let's say you want to list all the SubStations inside the plugin. +You can do so by using + +{% highlight ts %} +Array.from(doc.querySelectorAll('Substation')).map((substation) => substation.getAttribute('name')); +{% endhighlight %} + +{% highlight ts %} +import { html, css, LitElement, TemplateResult } from 'lit'; +import { property } from 'lit/decorators.js'; + +export default class OscdMyNewPlugin extends LitElement { + + @property({ type: Object }) + doc!: XMLDocument; + + @property({ type: Number }) + editCount = -1; + + @property({ type: String }) + locale!: string; + + renderSubstationNames(): TemplateResult { + return html`
    + ${Array + .from(this.doc.querySelectorAll('Substation')) + .map((substation) => substation.getAttribute('name')) + .map((name) => html`
  • ${name}
    • `) + }
`; + } + + render(): TemplateResult { + return html`
${this.renderSubstationNames()}
`; + } +{% endhighlight %} + +You can make the plugin as simple or difficult as you want. + + +# Building the plugin +After implementing your logic in the plugin, it's time to build the plugin. +Thankfully, the Open-WC standard provides us with npm scripts to easily build the plugin. + + +{% highlight ts %} +npm run build +{% endhighlight %} + +The script above creates the build output which can be hosted on GitHub for example. Just copy over the build directory and you're good to go. + +--- + +And that's it! You just successfully created and built a plugin that can be used with OpenSCD. + +In a different guide, we will cover more advanced things, like editing the SCL file. + +> If you're looking for the full code of this guide, [you can find it here](https://github.com/openscd/oscd-plugin-template). This repository also has templates for other frameworks. \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 00bba59..fda14f4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,7 +1,7 @@ services: jekyll: image: jekyll/jekyll:latest - command: jekyll serve --watch --force_polling --verbose --livereload + command: jekyll serve --watch --force_polling --verbose --livereload --trace ports: - 4000:4000 volumes: diff --git a/index.html b/index.html index 5c593b9..613b6f7 100644 --- a/index.html +++ b/index.html @@ -5,12 +5,12 @@ cover: home ---
- + Get started
-
+
diff --git a/pages/glossary.md b/pages/glossary.md index 6ba96f5..9e21363 100644 --- a/pages/glossary.md +++ b/pages/glossary.md @@ -3,6 +3,7 @@ layout: default title: Glossary subtitle: OpenSCD Glossary cover: solar +toc: true --- # OpenSCD Glossary diff --git a/pages/guides.md b/pages/guides.md index 21cc979..6128771 100644 --- a/pages/guides.md +++ b/pages/guides.md @@ -5,27 +5,29 @@ subtitle: Guides cover: solar --- -
-
-
-

- Guides -

-
-
-
{% for guide in site.guides %}
-
+
- {{ guide.name }} + {{ guide.title }} +
+
+ + schedule + {{ guide.content | reading_time }} + + + {% for i in (1..guide.difficulty) %} + grade + {% endfor %} +
{{ guide.summary }}
-
+
{% endfor %}