diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 00000000..c4fc584d --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,16 @@ +# Example sites + +- [vincent.is](https://vincent.is): https://gitlab.com/Keats/vincent.is +- [code Developer Settings > Personal Access Tokens`. +Generate a new token, and give it any description you'd like. +Under the "Select Scopes" section, give it repo permissions. Click "Generate token" to finish up. + +Your token will now be visible! +Copy it into your clipboard and head back to Travis. +Once on Travis, click on your project, and navigate to "Settings". Scroll down to "Environment Variables" and input a name of `GH_TOKEN` with a value of your access token. +Make sure "Display value in build log" is off, and then click add. Now Travis has access to your repository. + +## Setting up Travis + +We're almost done. We just need some scripts in a .travis.yml file to tell Travis what to do. + +```yaml +before_script: + # Download and unzip the gutenberg executable + # Replace the version numbers in the URL by the version you want to use + - curl -s -L https://github.com/Keats/gutenberg/releases/download/v0.3.1/gutenberg-v0.3.1-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin + +script: + - gutenberg build + +# If you are using a different folder than `public` for the output directory, you will +# need to change the `gutenberg` command and the `ghp-import` path +after_success: | + [ $TRAVIS_BRANCH = master ] && + [ $TRAVIS_PULL_REQUEST = false ] && + gutenberg build && + sudo pip install ghp-import && + ghp-import -n public && + git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages +``` + +If your site is using a custom domain, you will need to mention it in the `ghp-import` command: `ghp-import -c vaporsoft.net -n public` +for example. + +Credits: this page is based on the article https://vaporsoft.net/publishing-gutenberg-to-github/ diff --git a/docs/content/documentation/deployment/netlify.md b/docs/content/documentation/deployment/netlify.md new file mode 100644 index 00000000..e5fedc86 --- /dev/null +++ b/docs/content/documentation/deployment/netlify.md @@ -0,0 +1,44 @@ ++++ +title = "Netlify" +weight = 20 ++++ + +Netlify provides best practices like SSL, CDN distribution, caching and continuous deployment +with no effort. This very site is hosted by Netlify and automatically deployed on commits. + +If you don't have an account with Netlify, you can [sign up](https://app.netlify.com) for one. + +Once you are in the admin interface, you can add a site from a Git provider (GitHub, GitLab or Bitbucket). At the end + of this process, you can select the deploy settings for the project: + + - build command: `GUTENBERG_VERSION=0.3.1 gutenberg build` (replace the version number in the variable by the version you want to use) + - publish directory: the path to where the `public` directory is + +With this setup, your site should be automatically deployed on every commit on master. + +However, if you want to use everything that Netlify gives you, you should also publish temporary sites for pull requests. + +This is done by adding the following `netlify.toml` file in your repository and removing the build command/publish directory in +the admin interface. + +```toml +[build] +# assuming the gutenberg site is in a docs folder, if it isn't you don't need +# to have a `base` variable but you do need the `publish` and `command` +base = "docs" +publish = "docs/public" +command = "gutenberg build" + +[build.environment] +# Set the version name that you want to use and Netlify will automatically use it +GUTENBERG_VERSION = "0.3.1" + +# The magic for deploying previews of branches +# We need to override the base url with what the url of the preview is ($DEPLOY_PRIME_URL) +# otherwise links would not work properly +[context.deploy-preview] +command = "gutenberg build --base-url $DEPLOY_PRIME_URL" + +``` + + diff --git a/docs/content/documentation/deployment/overview.md b/docs/content/documentation/deployment/overview.md new file mode 100644 index 00000000..c776b263 --- /dev/null +++ b/docs/content/documentation/deployment/overview.md @@ -0,0 +1,9 @@ ++++ +title = "Overview" +weight = 10 ++++ + +Gutenberg outputs plain files, no databases needed. This makes hosting and deployment +trivial on many providers. + + diff --git a/docs/content/documentation/themes/creating-a-theme.md b/docs/content/documentation/themes/creating-a-theme.md index 6b1d2f3f..0ba63402 100644 --- a/docs/content/documentation/themes/creating-a-theme.md +++ b/docs/content/documentation/themes/creating-a-theme.md @@ -7,29 +7,25 @@ Creating is exactly like creating a normal site with Gutenberg, except you will want to use many [Tera blocks](https://tera.netlify.com/docs/templates/#inheritance) to allow users to easily modify it. -A theme also need to have a `theme.toml` configuration file with the -following fields, here's the one from a [real template](https://github.com/Keats/hyde): +## Getting started +As mentioned, a theme is just like any site: start with running `gutenberg init MY_THEME_NAME`. + +The only thing needed to turn that site into a theme is to add `theme.toml` configuration file with the +following fields: ```toml -name = "hyde" +name = "my theme name" description = "A classic blog theme" license = "MIT" homepage = "https://github.com/Keats/gutenberg-hyde" # The minimum version of Gutenberg required -min_version = "0.1" +min_version = "0.3" # Any variable there can be overriden in the end user `config.toml` # You don't need to prefix variables by the theme name but as this will # be merged with user data, some kind of prefix or nesting is preferable # Use snake_casing to be consistent with the rest of Gutenberg [extra] -hyde_sticky = true -hyde_reverse = false -hyde_theme = "" -hyde_links = [ - {url = "https://google.com", name = "Google.com"}, - {url = "https://google.fr", name = "Google.fr"}, -] # The theme author info: you! [author] @@ -44,21 +40,36 @@ homepage = "http://markdotto.com/" repo = "https://www.github.com/mdo/hyde" ``` -A theme will also need three directories to work: +A simple theme you can use as example is [Hyde](https://github.com/Keats/hyde). -- `static`: any static files used in this theme -- `templates`: all templates used in this theme -- `sass`: Sass stylesheets for this theme, can be empty +## Working on a theme +As a theme is just a site, you can simply use `gutenberg serve` and make changes to your +theme, with live reloading working as expected. -To be featured on this site, the theme will require two more things: +Make sure to commit every directory (including `content`) in order for other people +to be able to build the theme from your repository. -- `screenshot.png`: a screenshot of the theme in action, its size needs to be reasonable +### Caveat + +Please note that [include paths](https://tera.netlify.com/docs/templates/#include) can only be used in used in normal templates. +Theme templates should use [macros](https://tera.netlify.com/docs/templates/#macros) instead. + +## Submitting a theme to the gallery + +If you want your theme to be featured in the [themes](./themes/_index.md) section +of this site, the theme will require two more things: + +- `screenshot.png`: a screenshot of the theme in action with a max size of around 2000x1000 - `README.md`: a thorough README explaining how to use the theme and any other information of importance -A simple theme you can use as example is [Hyde](https://github.com/Keats/hyde). +The first step is to make sure the theme is fulfilling those three requirements: -# Caveat +- have a `screenshot.png` of the theme in action with a max size of around 2000x1000 +- have a thorough `README.md` explaining how to use the theme and any other information +of importance +- be of reasonably high quality -Please note that [include paths](https://tera.netlify.com/docs/templates/#include) can only be used in used in normal templates. Theme templates should use [macro's](https://tera.netlify.com/docs/templates/#macros) instead. +When your theme is ready, you can submit it to the [themes repository](https://github.com/Keats/gutenberg-themes) +by following the process in the README. diff --git a/docs/content/documentation/themes/themes-list.md b/docs/content/documentation/themes/themes-list.md deleted file mode 100644 index e25fde8c..00000000 --- a/docs/content/documentation/themes/themes-list.md +++ /dev/null @@ -1,9 +0,0 @@ -+++ -title = "List of themes" -weight = 40 -+++ - -The following themes are available for Gutenberg: - -- [Hyde](https://github.com/Keats/gutenberg-hyde) -- [Materialize](https://github.com/verpeteren/gutenberg-materialize) diff --git a/docs/content/themes/_index.md b/docs/content/themes/_index.md new file mode 100644 index 00000000..5aa2e7b5 --- /dev/null +++ b/docs/content/themes/_index.md @@ -0,0 +1,6 @@ + ++++ +template = "themes.html" +sort_by = "date" ++++ + \ No newline at end of file diff --git a/docs/content/themes/after-dark/index.md b/docs/content/themes/after-dark/index.md new file mode 100644 index 00000000..0d999e49 --- /dev/null +++ b/docs/content/themes/after-dark/index.md @@ -0,0 +1,70 @@ + ++++ +title = "after-dark" +description = "A robust, elegant dark theme" +template = "theme.html" +date = 2017-11-07T17:39:37+01:00 + +[extra] +created = 2018-02-22T19:13:36+01:00 +updated = 2017-11-07T17:39:37+01:00 +repository = "https://github.com/Keats/after-dark" +homepage = "https://github.com/Keats/after-dark" +minimum_version = "0.2" +license = "MIT" + +[extra.author] +name = "Vincent Prouillet" +homepage = "https://vincent.is" ++++ + +# after-dark + +![after-dark screenshot](https://github.com/Keats/after-dark/blob/master/screenshot.png?raw=true) + +## Contents + +- [Installation](#installation) +- [Options](#options) + - [Top menu](#top-menu) + - [Title](#title) + +## Installation +First download this theme to your `themes` directory: + +```bash +$ cd themes +$ git clone https://github.com/Keats/after-dark.git +``` +and then enable it in your `config.toml`: + +```toml +theme = "after-dark" +``` + +## Options + +### Top-menu +Set a field in `extra` with a key of `after_dark_menu`: + +```toml +after_dark_menu = [ + {url = "$BASE_URL", name = "Home"}, + {url = "$BASE_URL/categories", name = "Categories"}, + {url = "$BASE_URL/tags", name = "Tags"}, + {url = "https://google.com", name = "Google"}, +] +``` + +If you put `$BASE_URL` in a url, it will automatically be replaced by the actual +site URL. + +### Title +The site title is shown on the homepage. As it might be different from the `` +element that the `title` field in the config represents, you can set the `after_dark_title` +instead. + +## Original +This template is based on the Hugo template https://github.com/comfusion/after-dark + + \ No newline at end of file diff --git a/docs/content/themes/after-dark/screenshot.png b/docs/content/themes/after-dark/screenshot.png new file mode 100644 index 00000000..e34718d6 Binary files /dev/null and b/docs/content/themes/after-dark/screenshot.png differ diff --git a/docs/content/themes/book/index.md b/docs/content/themes/book/index.md new file mode 100644 index 00000000..7edd3ad1 --- /dev/null +++ b/docs/content/themes/book/index.md @@ -0,0 +1,58 @@ + ++++ +title = "book" +description = "A book theme inspired from GitBook/mdBook" +template = "theme.html" +date = 2018-01-28T10:53:19+01:00 + +[extra] +created = 2018-02-22T19:13:36+01:00 +updated = 2018-01-28T10:53:19+01:00 +repository = "https://github.com/Keats/book" +homepage = "https://github.com/Keats/book" +minimum_version = "0.2" +license = "MIT" + +[extra.author] +name = "Vincent Prouillet" +homepage = "https://vincent.is" ++++ + +# book + +A theme based on [Gitbook](https://www.gitbook.com), to write documentation +or books. + +![book screenshot](https://github.com/Keats/book/blob/master/screenshot.png?raw=true) + + +## Contents + +- [Installation](#installation) +- [Options](#options) + - [Numbered chapters](#numbered-chapters) + +## Installation +First download this theme to your `themes` directory: + +```bash +$ cd themes +$ git clone https://github.com/Keats/book.git +``` +and then enable it in your `config.toml`: + +```toml +theme = "book" +``` + +## Options + +### Numbered chapters +By default, the `book` theme will number the chapters and pages in the left menu. +You can disable that by setting the `book_numbered_chapters` in `extra`: + +```toml +book_numbered_chapters = false +``` + + \ No newline at end of file diff --git a/docs/content/themes/book/screenshot.png b/docs/content/themes/book/screenshot.png new file mode 100644 index 00000000..d4dfd078 Binary files /dev/null and b/docs/content/themes/book/screenshot.png differ diff --git a/docs/content/themes/even/index.md b/docs/content/themes/even/index.md new file mode 100644 index 00000000..6e83d0e8 --- /dev/null +++ b/docs/content/themes/even/index.md @@ -0,0 +1,69 @@ + ++++ +title = "even" +description = "A robust, elegant dark theme" +template = "theme.html" +date = 2018-01-25T18:44:44+01:00 + +[extra] +created = 2018-02-22T19:13:36+01:00 +updated = 2018-01-25T18:44:44+01:00 +repository = "https://github.com/Keats/even" +homepage = "https://github.com/Keats/even" +minimum_version = "0.3" +license = "MIT" + +[extra.author] +name = "Vincent Prouillet" +homepage = "https://vincent.is" ++++ + +# Even +Even is a clean, responsive theme based on the Hugo theme with the same name featuring categories, tags and pagination. + +![even screenshot](https://github.com/Keats/even/blob/master/screenshot.png?raw=true) + +## Contents + +- [Installation](#installation) +- [Options](#options) + - [Top menu](#top-menu) + - [Title](#title) + +## Installation +First download this theme to your `themes` directory: + +```bash +$ cd themes +$ git clone https://github.com/Keats/even.git +``` +and then enable it in your `config.toml`: + +```toml +theme = "even" +``` + +## Options + +### Top-menu +Set a field in `extra` with a key of `even_menu`: + +```toml +# This is the default menu +even_menu = [ + {url = "$BASE_URL", name = "Home"}, + {url = "$BASE_URL/categories", name = "Categories"}, + {url = "$BASE_URL/tags", name = "Tags"}, + {url = "$BASE_URL/about", name = "About"}, +] +``` + +If you put `$BASE_URL` in a url, it will automatically be replaced by the actual +site URL. + +### Title +The site title is shown on the header. As it might be different from the `<title>` +element that the `title` field in the config represents, you can set the `even_title` +instead. + + \ No newline at end of file diff --git a/docs/content/themes/even/screenshot.png b/docs/content/themes/even/screenshot.png new file mode 100644 index 00000000..1acdd623 Binary files /dev/null and b/docs/content/themes/even/screenshot.png differ diff --git a/docs/content/themes/hyde/index.md b/docs/content/themes/hyde/index.md new file mode 100644 index 00000000..e11e16a2 --- /dev/null +++ b/docs/content/themes/hyde/index.md @@ -0,0 +1,89 @@ + ++++ +title = "hyde" +description = "A classic blog theme" +template = "theme.html" +date = 2017-10-24T15:01:52+02:00 + +[extra] +created = 2018-01-25T18:45:36+01:00 +updated = 2017-10-24T15:01:52+02:00 +repository = "https://github.com/Keats/hyde" +homepage = "https://github.com/Keats/gutenberg-hyde" +minimum_version = "0.2" +license = "MIT" + +[extra.author] +name = "Vincent Prouillet" +homepage = "https://vincent.is" ++++ + +# hyde +Hyde is a brazen two-column [Gutenberg](https://github.com/Keats/gutenberg) based on the Jekyll theme of the same name that pairs a prominent sidebar with uncomplicated content. + +![Hyde screenshot](https://f.cloud.github.com/assets/98681/1831228/42af6c6a-7384-11e3-98fb-e0b923ee0468.png) + + +## Contents + +- [Installation](#installation) +- [Options](#options) + - [Sidebar menu](#sidebar-menu) + - [Sticky sidebar content](#sticky-sidebar-content) + - [Themes](#themes) + - [Reverse layout](#reverse-layout) + +## Installation +First download this theme to your `themes` directory: + +```bash +$ cd themes +$ git clone https://github.com/Keats/hyde.git +``` +and then enable it in your `config.toml`: + +```toml +theme = "hyde" +``` + +## Options + +### Sidebar menu +Set a field in `extra` with a key of `hyde_links`: +```toml +[extra] +hyde_links = [ + {url = "https://google.com", name = "Google.com"}, + {url = "https://google.fr", name = "Google.fr"}, +] +``` +Each link needs to have a `url` and a `name`. + +### Sticky sidebar content +By default Hyde ships with a sidebar that affixes it's content to the bottom of the sidebar. You can optionally disable this by setting `hyde_sticky` to false in your `config.toml`. + +### Themes +Hyde ships with eight optional themes based on the [base16 color scheme](https://github.com/chriskempson/base16). Apply a theme to change the color scheme (mostly applies to sidebar and links). + +![Hyde in red](https://f.cloud.github.com/assets/98681/1831229/42b0b354-7384-11e3-8462-31b8df193fe5.png) + +There are eight themes available at this time. + +![Hyde theme classes](https://f.cloud.github.com/assets/98681/1817044/e5b0ec06-6f68-11e3-83d7-acd1942797a1.png) + +To use a theme, set the `hyde_theme` field in `config.toml` to any of the themes name: + +```toml +[extra] +hyde_theme = "theme-base-08" +``` + +To create your own theme, look to the Themes section of [included CSS file](https://github.com/poole/hyde/blob/master/public/css/hyde.css). Copy any existing theme (they're only a few lines of CSS), rename it, and change the provided colors. + +### Reverse layout + +![Hyde with reverse layout](https://f.cloud.github.com/assets/98681/1831230/42b0d3ac-7384-11e3-8d54-2065afd03f9e.png) + +Hyde's page orientation can be reversed by setting `hyde_reversed` to `true` in the `config.toml`. + + \ No newline at end of file diff --git a/docs/content/themes/hyde/screenshot.png b/docs/content/themes/hyde/screenshot.png new file mode 100644 index 00000000..5e218059 Binary files /dev/null and b/docs/content/themes/hyde/screenshot.png differ diff --git a/docs/sass/_themes.scss b/docs/sass/_themes.scss new file mode 100644 index 00000000..3b89053d --- /dev/null +++ b/docs/sass/_themes.scss @@ -0,0 +1,50 @@ + +.themes-container { + padding: 3rem; + + img { + max-width: 100%; + } +} + +.themes { + display: flex; + flex-wrap: wrap; + justify-content: space-between; + + .theme { + width: 30%; + text-decoration: none; + cursor: pointer; + margin-bottom: 2rem; + border-bottom: none; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.4); + padding: 10px; + + img { + width: 100%; + } + + span { + display: block; + text-align: center; + } + } +} + +.theme-info { + display: flex; + align-items: flex-start; + + .thumb { + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.07); + width: 400px; + margin-right: 2rem; + } + + h1, p { + margin: 0; + } + + padding: 1rem; +} diff --git a/docs/sass/site.scss b/docs/sass/site.scss index bae6b5d7..fadaa37b 100644 --- a/docs/sass/site.scss +++ b/docs/sass/site.scss @@ -15,3 +15,4 @@ $link-color: #007CBC; @import "header"; @import "index"; @import "docs"; +@import "themes"; diff --git a/docs/templates/index.html b/docs/templates/index.html index c366dbb9..5b3bac13 100644 --- a/docs/templates/index.html +++ b/docs/templates/index.html @@ -16,6 +16,7 @@ <nav class="{% block extra_nav_class %}container{% endblock extra_nav_class %}"> <a class="header__logo white" href="{{ config.base_url }}">Gutenberg</a> <a class="white" href="{{ get_url(path="./documentation/_index.md") }}" class="nav-link">Docs</a> + <a class="white" href="{{ get_url(path="./themes/_index.md") }}" class="nav-link">Themes</a> <a class="white" href="https://github.com/Keats/gutenberg" class="nav-link">GitHub</a> </nav> </header> @@ -90,7 +91,7 @@ {% endblock content %} </div> <footer> - ©2017 — <a class="white" href="https://vincent.is">Vincent Prouillet</a> and <a class="white" href="https://github.com/Keats/gutenberg/graphs/contributors">contributors</a> + ©2017-2018 — <a class="white" href="https://vincent.is">Vincent Prouillet</a> and <a class="white" href="https://github.com/Keats/gutenberg/graphs/contributors">contributors</a> </footer> </body> </html> diff --git a/docs/templates/theme.html b/docs/templates/theme.html new file mode 100644 index 00000000..85bf745c --- /dev/null +++ b/docs/templates/theme.html @@ -0,0 +1,19 @@ +{% extends "themes.html" %} + +{% block title %}{{ page.title }} | Gutenberg {% endblock title %} +{% block theme_content %} + <div class="theme-info"> + <img src="{{page.permalink}}screenshot.png" class="thumb"> + <div class="metadata"> + <h1>{{ page.title }}</h1> + <p>{{ page.description }}</p> + <p><b>Author:</b> {{page.extra.author.name}}</p> + <p><b>License:</b> {{page.extra.license}}</p> + <p><b>Homepage:</b> {{page.extra.homepage}}</p> + <p><b>Last updated:</b> {{page.extra.updated }}</p> + </div> + </div> + + <hr> + {{page.content | safe}} +{% endblock theme_content %} diff --git a/docs/templates/themes.html b/docs/templates/themes.html new file mode 100644 index 00000000..e4dcb7d5 --- /dev/null +++ b/docs/templates/themes.html @@ -0,0 +1,22 @@ +{% extends "index.html" %} + +{% block extra_nav_class %}{% endblock extra_nav_class %} +{% block extra_content_class %}content--reversed{% endblock extra_content_class %} + +{% block title %}Themes | {{ super() }} {% endblock title %} + +{% block content %} + <div class="themes-container"> + {% block theme_content %} + <h1>Gutenberg themes</h1> + <div class="themes"> + {% for theme in section.pages %} + <a class="theme" href="{{theme.permalink}}"> + <img src="{{theme.permalink}}screenshot.png" alt="Screenshot of {{theme.title}}"> + <span>{{theme.title}}</span> + </a> + {% endfor %} + </div> + {% endblock theme_content %} + </div> +{% endblock content %} diff --git a/netlify.toml b/netlify.toml index 26591ef2..4819cd5f 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,8 +1,10 @@ [build] - base = "docs" - publish = "docs/public" - command = "curl -sL https://github.com/Keats/gutenberg/releases/download/v0.2.1/gutenberg-v0.2.1-x86_64-unknown-linux-gnu.tar.gz | tar zxvf - && /opt/build/repo/docs/gutenberg build" + base = "docs" + publish = "docs/public" + command = "gutenberg build" + +[build.environment] + GUTENBERG_VERSION = "0.3.1" [context.deploy-preview] - command = "curl -sL https://github.com/Keats/gutenberg/releases/download/v0.2.1/gutenberg-v0.2.1-x86_64-unknown-linux-gnu.tar.gz | tar zxvf - && /opt/build/repo/docs/gutenberg build --base-url $DEPLOY_PRIME_URL" - + command = "gutenberg build --base-url $DEPLOY_PRIME_URL"