From c348648b028338889c068b95aa752ac00557c8d5 Mon Sep 17 00:00:00 2001 From: Vincent Prouillet Date: Wed, 4 Oct 2017 00:21:18 +0900 Subject: [PATCH] Some design work on docs --- CHANGELOG.md | 3 + README.md | 2 + docs/config.toml | 1 + .../documentation/content/shortcodes.md | 14 ++-- .../getting-started/cli-usage.md | 3 + .../getting-started/configuration.md | 13 +++- .../getting-started/installation.md | 2 +- docs/content/documentation/themes/_index.md | 1 + .../themes/installing-and-using-themes.md | 6 +- docs/sass/_base.scss | 12 ++- docs/sass/_docs.scss | 73 ++++++++++++++++--- docs/templates/documentation.html | 6 +- docs/templates/index.html | 9 ++- docs/templates/page.html | 2 +- 14 files changed, 110 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3943d67..8021ffb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ - Add config to sitemap template - Add `permalink` to all taxonomy items (tags & categories) - Tags in the tags page are now sorting alphabetically instead of by number of pages in them +- Remove deprecated `link` param of `get_url` +- Add 1337 color scheme +- Defaults to compressed Sass output ## 0.1.3 (2017-08-31) diff --git a/README.md b/README.md index 839668d..72601c9 100644 --- a/README.md +++ b/README.md @@ -338,9 +338,11 @@ In case of shortcodes with a body, the body will be passed as the `body` variabl ### Adding a syntax Syntax highlighting depends on submodules so ensure you load them first: + ```bash $ git submodule update --init ``` + Gutenberg only works with syntaxes in the `.sublime-syntax` format. If your syntax is in `.tmLanguage` format, open it in Sublime Text and convert it to `sublime-syntax` by clicking on Tools > Developer > New Syntax from ... and put it at the root of `sublime_syntaxes`. diff --git a/docs/config.toml b/docs/config.toml index 73d5349..a29fd38 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -5,6 +5,7 @@ description = "Everything you need to make a static site engine in one binary. A compile_sass = true highlight_code = true insert_anchor_links = true +highlight_theme = "kronuz" [extra] author = "Vincent Prouillet" diff --git a/docs/content/documentation/content/shortcodes.md b/docs/content/documentation/content/shortcodes.md index c1363c2..94f4ebe 100644 --- a/docs/content/documentation/content/shortcodes.md +++ b/docs/content/documentation/content/shortcodes.md @@ -46,11 +46,11 @@ On a new line, call the shortcode as if it was a function in a variable block. A calls of the YouTube shortcode. ```md -{{ youtube(id="w7Ft2ymGmfc") }} +{{ youtube(id="dQw4w9WgXcQ") }} -{{ youtube(id="w7Ft2ymGmfc", autoplay=true) }} +{{ youtube(id="dQw4w9WgXcQ", autoplay=true) }} -{{ youtube(id="w7Ft2ymGmfc", autoplay=true, class="youtube") }} +{{ youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") }} ``` ### Shortcodes with body @@ -93,16 +93,16 @@ The arguments are: Usage example: ```md -{{ youtube(id="w7Ft2ymGmfc") }} +{{ youtube(id="dQw4w9WgXcQ") }} -{{ youtube(id="w7Ft2ymGmfc", autoplay=true) }} +{{ youtube(id="dQw4w9WgXcQ", autoplay=true) }} -{{ youtube(id="w7Ft2ymGmfc", autoplay=true, class="youtube") }} +{{ youtube(id="dQw4w9WgXcQ", autoplay=true, class="youtube") }} ``` Result example: -{{ youtube(id="w7Ft2ymGmfc") }} +{{ youtube(id="dQw4w9WgXcQ") }} ### Vimeo Embed a player for a Vimeo video. diff --git a/docs/content/documentation/getting-started/cli-usage.md b/docs/content/documentation/getting-started/cli-usage.md index fc13493..ebcddd3 100644 --- a/docs/content/documentation/getting-started/cli-usage.md +++ b/docs/content/documentation/getting-started/cli-usage.md @@ -41,3 +41,6 @@ $ gutenberg serve --interface 0.0.0.0 --port 2000 The serve command will watch all your content and will provide live reload, without hard refresh if possible. + +If you fail to see your change, this means that Gutenberg couldn't reload that bit and you will +need to restart `gutenberg serve`. diff --git a/docs/content/documentation/getting-started/configuration.md b/docs/content/documentation/getting-started/configuration.md index a3a2717..1fafebb 100644 --- a/docs/content/documentation/getting-started/configuration.md +++ b/docs/content/documentation/getting-started/configuration.md @@ -29,7 +29,8 @@ theme = "" # Highlight all code blocks found highlight_code = false -# Which theme to use for the code highlighting. See below for list of accepted values +# Which theme to use for the code highlighting. +# See below for list of accepted values highlight_theme = "base16-ocean-dark" # Whether to generate a RSS feed automatically @@ -38,16 +39,19 @@ generate_rss = false # The number of articles to include in the RSS feed rss_limit = 20 -# Whether to generate a tags page and individual tag pages for pages with tags +# Whether to generate a tags page and individual +# tag pages for pages with tags generate_tags_pages = false -# Whether to generate a categories page and individual category pages for pages with a category +# Whether to generate a categories page and individual +# category pages for pages with a category generate_categories_pages = false # Whether to compile the Sass files found in the `sass` directory compile_sass = false -# You can put any kind of data in there and it will be accessible in all templates +# You can put any kind of data in there and it +# will be accessible in all templates [extra] ``` @@ -66,6 +70,7 @@ Gutenberg currently has the following highlight themes available: - monokai - solarized-dark - solarized-light +- 1337 Gutenberg uses the Sublime Text themes, making it very easy to add more. If you want a theme not on that list, please open an issue or a pull request on the [Gutenberg repo](https://github.com/Keats/gutenberg). diff --git a/docs/content/documentation/getting-started/installation.md b/docs/content/documentation/getting-started/installation.md index 16605f5..ce55327 100644 --- a/docs/content/documentation/getting-started/installation.md +++ b/docs/content/documentation/getting-started/installation.md @@ -6,7 +6,7 @@ weight = 1 Gutenberg provides pre-built binaries for Mac OS, Linux and Windows on the [Github release page](https://github.com/Keats/gutenberg/releases). -## Using brew on Mac OS +## Mac OS TODO: it's not on brew right now diff --git a/docs/content/documentation/themes/_index.md b/docs/content/documentation/themes/_index.md index 938a8e2..6f8f414 100644 --- a/docs/content/documentation/themes/_index.md +++ b/docs/content/documentation/themes/_index.md @@ -2,4 +2,5 @@ title = "Themes" weight = 4 sort_by = "weight" +insert_anchor_links = "left" +++ diff --git a/docs/content/documentation/themes/installing-and-using-themes.md b/docs/content/documentation/themes/installing-and-using-themes.md index a7c1014..3f164ea 100644 --- a/docs/content/documentation/themes/installing-and-using-themes.md +++ b/docs/content/documentation/themes/installing-and-using-themes.md @@ -33,9 +33,9 @@ Any file from the theme can be overriden by creating a file with the same path a directory. Here are a few examples of that, assuming the theme name is `simple-blog`: ```plain -templates/pages/post.html -> will override themes/simple-blog/pages/post.html -templates/macros.html -> will override themes/simple-blog/macros.html -static/js/site.js -> will override themes/simple-blog/static/js/site.jss +templates/pages/post.html -> replace themes/simple-blog/pages/post.html +templates/macros.html -> replace themes/simple-blog/macros.html +static/js/site.js -> replace themes/simple-blog/static/js/site.jss ``` Most themes will also provide some variables that are meant to be overriden: this happens in the `extra` section diff --git a/docs/sass/_base.scss b/docs/sass/_base.scss index c935772..1ecc17f 100644 --- a/docs/sass/_base.scss +++ b/docs/sass/_base.scss @@ -4,7 +4,7 @@ html, body { } body { - font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; + font-family: "Fira Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; line-height: 1.6; background-color: $background; color: $foreground; @@ -56,7 +56,6 @@ a { &:active { background-color: #f6f9fc; transform: translateY(1px); - // box-shadow: 0 4px 6px rgba(50, 50, 93, 0.11), 0 1px 3px rgba(0, 0, 0, .08); } } } @@ -65,3 +64,12 @@ pre { padding: 1rem; overflow: auto; } + +p code, li code { + background-color: #f5f5f5; + white-space: pre-wrap; + padding: 5px; + border-radius: 5px; + font-size: 0.85rem; + box-shadow: 0 1px 3px rgba(0,0,0,.1), 0 1px 1px rgba(0,0,0,.1), 0 2px 1px -1px rgba(0,0,0,.12); +} diff --git a/docs/sass/_docs.scss b/docs/sass/_docs.scss index 5405e2a..ae318e2 100644 --- a/docs/sass/_docs.scss +++ b/docs/sass/_docs.scss @@ -8,35 +8,86 @@ ul { padding-left: 0; list-style: none; + } + + > ul { + > li { + margin-bottom: 1rem; + } + + .documentation__sidebar__title { + font-size: 1.25rem; + font-weight: bold; + } ul { - padding-left: 1rem; + margin-top: 0.25rem; + + li { + border-left: 1px solid $background; + padding-left: 0.75rem; + padding-top: 0.25rem; + padding-bottom: 0.25rem; + } li.active a { - color: red; + font-weight: bold; + border-bottom: 1px solid $background; } } } + + a { + color: $background; + padding-bottom: 2px; + border-bottom: 1px solid rgba(25, 25, 25, 0.25); + text-decoration: none; + + &:hover { + border-bottom: 1px solid $background; + } + } } &__content { - flex: 1; - } + width: 60%; + // Same as the anchor absolute left to not overlap + margin-left: 2rem; - a { - color: $background; - padding-bottom: 2px; - border-bottom: 1px solid $background; + h1, h2, h3, h4, h5, h6 { + .gutenberg-anchor { + font-size: 1.25rem; + visibility: hidden; + margin-left: -2rem; + text-decoration: none; + border-bottom-color: transparent; + cursor: pointer; + } - &:hover { - text-decoration: none; + &:hover { + .gutenberg-anchor { + visibility: visible; + } + } } - &:visited { + a { color: $background; + padding-bottom: 2px; + border-bottom: 1px solid $background; + cursor: pointer; + + &:hover { + text-decoration: none; + } + + &:visited { + color: $background; + } } } + iframe { width: 100%; min-height: 400px; diff --git a/docs/templates/documentation.html b/docs/templates/documentation.html index 3734a8f..03fc8c1 100644 --- a/docs/templates/documentation.html +++ b/docs/templates/documentation.html @@ -1,17 +1,15 @@ {% extends "index.html" %} -{% block title %}{{ super() }} - Documentation {% endblock title %} - {% block extra_content_class %}content--reversed{% endblock extra_content_class %} {% block content %} {% set section = get_section(path="documentation/_index.md") %} -
+
@@ -60,7 +60,8 @@

Easy to use

- Gutenberg strives for good UX and being productive instantly. + Gutenberg gets out of your way so you can focus on what + you are actually making.

diff --git a/docs/templates/page.html b/docs/templates/page.html index 10d1a98..8f6c09b 100644 --- a/docs/templates/page.html +++ b/docs/templates/page.html @@ -1,6 +1,6 @@ {% extends "documentation.html" %} -{% block title %}{{ super() }} - {{ page.title }} {% endblock title %} +{% block title %}{{ page.title }} | {{ super() }} {% endblock title %} {% block doc_content %}

{{page.title}}

{{page.content | safe}}