diff --git a/EXAMPLES.md b/EXAMPLES.md index 27cd2e2a..a5fb60fc 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -1,18 +1,19 @@ # Example sites -- [vincent.is](https://vincent.is): https://gitlab.com/Keats/vincent.is -- [code https://mywebsite.com/blog/configuration/ +    └── _index.md // -> https://mywebsite.com/blog/ +``` + +If you wanted to add an image to the `https://mywebsite.com/blog/configuration` page, you would +have three options: + * You could save the image to the `content/blog/configuration` folder and then link it with a + relative path from the `index.md` page. This is the approach described under **colocation**, + above. + * You could save the image to a `static/blog/configuration` folder and link it in exactly the + same way as if you had colocated it. If you do this, the generated files will be identical to + if you had colocated; the only difference will be that all static files will be saved in the + static folder rather than in the content folder. Depending on your organizational needs, this + may be better or worse. + * Or you could save the image to some arbitrary folder within the static folder. For example, + you could save all images to `static/images`. Using this approach, you would no longer be able + to use relative links, but could use an absolute link to `images/[filename]` to access your + image. This might be preferable for small sites or for sites that associate images with + multiple pages (e.g., logo images that appear on every page). diff --git a/docs/content/documentation/deployment/netlify.md b/docs/content/documentation/deployment/netlify.md index e5fedc86..e57b1c1d 100644 --- a/docs/content/documentation/deployment/netlify.md +++ b/docs/content/documentation/deployment/netlify.md @@ -8,13 +8,16 @@ with no effort. This very site is hosted by Netlify and automatically deployed o If you don't have an account with Netlify, you can [sign up](https://app.netlify.com) for one. +## Automatic Deploys 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) + - build command: `GUTENBERG_VERSION=0.3.3 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. +With this setup, your site should be automatically deployed on every commit on master. For `GUTENBERG_VERSION`, you may +use any of the tagged `release` versions in the GitHub repository—Netlify will automatically fetch the tagged version +and use it to build your site. However, if you want to use everything that Netlify gives you, you should also publish temporary sites for pull requests. @@ -31,14 +34,33 @@ 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" +GUTENBERG_VERSION = "0.3.3" # 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 +# We need to override the base url with whatever url Netlify assigns to our +# preview site. We do this using the Netlify environment variable +# `$DEPLOY_PRIME_URL`. + [context.deploy-preview] command = "gutenberg build --base-url $DEPLOY_PRIME_URL" ``` +## Manual Deploys +If you would prefer to use a version of Gutenberg that isn't a tagged release (for example, after having built Gutenberg from +source and made modifications), then you will need to manually deploy your `public` folder to Netlify. You can do this through +Netlify's web GUI or via the command line. +For a command-line manual deploy, follow these steps: + 1. Generate a `Personal Access Token` from the settings section of your Netlify account (*not* an OAuth Application) + 2. Build your site with `gutenberg build` + 3. Create a zip folder containing the `public` directory + 4. Run the `curl` command below, filling in your values for PERSONAL_ACCESS_TOKEN_FROM_STEP_1, FILE_NAME.zip and SITE_NAME + 5. (Optional) delete the zip folder + +```bash +curl -H "Content-Type: application/zip" \ + -H "Authorization: Bearer PERSONAL_ACCESS_TOKEN_FROM_STEP_1" \ + --data-binary "@FILE_NAME.zip" \ + https://api.netlify.com/api/v1/sites/SITE_NAME.netlify.com/deploys +``` diff --git a/docs/content/documentation/templates/overview.md b/docs/content/documentation/templates/overview.md index 6b88a98f..c2179df7 100644 --- a/docs/content/documentation/templates/overview.md +++ b/docs/content/documentation/templates/overview.md @@ -10,11 +10,7 @@ As this documentation will only talk about how templates work in Gutenberg, plea the [Tera template documentation](https://tera.netlify.com/docs/templates/) if you want to learn more about it first. -All templates live in the `templates` directory and built-in or themes templates can -be overriden by creating a template with same name in the correct path. For example, -you can override the RSS template by creating a `templates/rss.xml` file. - -If you are not sure what variables are available in a template, you can just stick `{{ __tera_context }}` in it +All templates live in the `templates` directory. If you are not sure what variables are available in a template, you can just stick `{{ __tera_context }}` in it to print the whole context. A few variables are available on all templates minus RSS and sitemap: @@ -23,6 +19,41 @@ A few variables are available on all templates minus RSS and sitemap: - `current_path`: the path (full URL without the `base_url`) of the current page, never starting with a `/` - `current_url`: the full URL for that page +## Standard Templates +By default, Gutenberg will look for three templates: `index.html`, which is applied +to the site homepage; `section.html`, which is applied to all sections (any HTML +page generated by creating a directory within your `content` directory); and +`page.html`, which is applied to all pages (any HTML page generated by creating a +`.md` file within your `content` directory). + +The homepage is always a section (regardless of whether it contains other pages). +Thus, the `index.html` and `section.html` templates both have access to the +section variables. The `page.html` template has access to the page variables. +The page and section variables are described in more detail in the next section of this documentation. + +## Built-in Templates +Gutenberg comes with three built-in templates: `rss.xml`, `sitemap.xml`, and +`robots.txt` (each described in their own section of this documentation). +Additionally, themes can add their own templates, which will be applied if not +overridden. You can override built-in or theme templates by creating a template with +same name in the correct path. For example, you can override the RSS template by +creating a `templates/rss.xml` file. + +## Custom Templates +In addition to the standard `index.html`, `section.html`, and `page.html` templates, +you may also create custom templates by creating a `.html` file in the `templates` +directory. These custom templates will not be used by default. Instead, the custom template will _only_ be used if you apply it by setting the `template` front-matter variable to the path for that template (or if you `include` it in another template that is applied). For example, if you created a custom template for your site's About page called `about.html`, you could apply it to your `about.md` page by including the following front matter in your `about.md` page: + +```md ++++ +title = "About Us" +template = "about.html" ++++ +``` + +Custom templates are not required to live at the root of your `templates` directory. +For example, `product_pages/with_pictures.html` is a valid template. + ## Built-in filters Gutenberg adds a few filters, in addition of the ones already present in Tera. diff --git a/docs/content/documentation/templates/rss.md b/docs/content/documentation/templates/rss.md index f96824d8..6633043a 100644 --- a/docs/content/documentation/templates/rss.md +++ b/docs/content/documentation/templates/rss.md @@ -3,9 +3,12 @@ title = "RSS" weight = 50 +++ -Gutenberg will look for a `rss.xml` file in the `templates` directory or -use the built-in one. Currently it is only possible to have one RSS feed for the whole -site, you cannot create a RSS feed per section or taxonomy. +If the site `config.toml` file sets `generate_rss = true`, then Gutenberg will +generate an `rss.xml` page for the site, which will live at `base_url/rss.xml`. To +generate the `rss.xml` page, Gutenberg will look for a `rss.xml` file in the `templates` +directory or, if one does not exist, will use the use the built-in rss template. +Currently it is only possible to have one RSS feed for the whole site; you cannot +create a RSS feed per section or taxonomy. **Only pages with a date and that are not draft will be available.** diff --git a/docs/content/themes/after-dark/index.md b/docs/content/themes/after-dark/index.md index 0d999e49..8b75931b 100644 --- a/docs/content/themes/after-dark/index.md +++ b/docs/content/themes/after-dark/index.md @@ -67,4 +67,4 @@ 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/templates/theme.html b/docs/templates/theme.html index 16402145..344e5244 100644 --- a/docs/templates/theme.html +++ b/docs/templates/theme.html @@ -10,6 +10,9 @@

Author: {{page.extra.author.name}}

License: {{page.extra.license}}

Homepage: {{page.extra.homepage}}

+ {% if page.extra.live_demo%} +

Live Demo: {{page.extra.live_demo}}

+ {% endif %}

Last updated: {{page.extra.updated }}

diff --git a/snapcraft.yaml b/snapcraft.yaml index b51def43..9d9194a8 100644 --- a/snapcraft.yaml +++ b/snapcraft.yaml @@ -19,3 +19,7 @@ parts: gutenberg: plugin: rust rust-channel: stable + build-packages: + - build-essential + - cmake + - git-core