save work

weru

30.04.2020 dfad1ec43b34f84ddcee2b94ea2641fe0d798a6c

save work

 .gitignore

@@ -1,4 +1,3 @@
public/
resources/
node_modules/
.DS_Store

 LICENSE

New file
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2020 Weru

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

 README.md

@@ -1,37 +1,28 @@
# Compose

Compose is a [Hugo](https://gohugo.io/) theme for technical documentation sets, providing simple navigation, site structure, and more.
Compose is a [Hugo](https://gohugo.io/) docs theme, inspired by [forestry.io](forestry.io)'s. 

This is not an officially supported Google product. This project is actively being maintained.
The theme provides a simple navigation & structure.

## Prerequisites
![Hugo Compose Theme](https://github.com/onweru/compose/blob/master/images/screenshot.png)

The following are basic prerequisites for using compose in your site:
## Installation 

- Install a recent release of the Hugo "extended" version (we recommend version 0.53 or later). If you install from the 
  [release page](https://github.com/gohugoio/hugo/releases), make sure you download the `_extended` version 
  which supports sass.
Install a recent release of the Hugo "extended" version; ideally versions `>= 0.61`. If you install from [hugo releases page](https://github.com/gohugoio/hugo/releases),  download the `_extended` version, which supports sass.

## Example and usage
## Example 

You can find an example project that uses Compose in the [Compose Example Project repo](https://github.com/onweru/compose). The Compose Example Project is hosted at [https://example.Compose.dev/](https://example.Compose.dev/).
You can find an example project that uses Compose in the [Compose Userguide](https://github.com/onweru/compose-userguide). 

To use the Compose theme for your own site:
The Compose Example Project is hosted at [https://compose-docs.netlify.com](https://compose-docs.netlify.com). This project also stands as the theme's user guide.

  - (Recommended) Copy the [example project](https://github.com/onweru/compose), which includes the Compose theme as a submodule.
    You can customize this pre-configured basic site into your own Compose themed site. [Learn more...](https://github.com/onweru/compose)
  
  - Add Compose to your existing Hugo site repo's `themes` directory. You can either add Compose as a Git submodule, or clone the Compose theme into your project.
> This guide covers the necessary bits. As the project evolves, the userguide will get more comprehensive

See the [Compose Getting Started Guide](https://Compose.dev/docs/getting-started/) for details about the various usage options.

## Documentation

Compose has its own user guide (using Compose, of course!) with lots more information about using the theme, which you can find at [https://Compose.dev/](https://Compose.dev/). Alternatively you can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above:
You can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above:

```
git clone --recurse-submodules --depth 1 https://github.com/onweru/compose.git
cd compose/userguide/
cd compose/exampleSite/
hugo server --themesDir ../..
```


 assets/js/index.js

@@ -136,15 +136,17 @@
      tocs.forEach(function(toc){
        toc.id = "";
        pushClass(toc, 'toc');
        const tocItems = Array.from(toc.children[0].children);

        const previousHeading = toc.previousElementSibling;
        previousHeading.matches('.active') ? pushClass(toc, tocActive) : false;
        if(toc.children.length >= 1) {
          const tocItems = Array.from(toc.children[0].children);
  
        tocItems.forEach(function(item){
          pushClass(item, 'toc_item');
          pushClass(item.firstElementChild, 'toc_link');
        })
          const previousHeading = toc.previousElementSibling;
          previousHeading.matches('.active') ? pushClass(toc, tocActive) : false;
    
          tocItems.forEach(function(item){
            pushClass(item, 'toc_item');
            pushClass(item.firstElementChild, 'toc_link');
          })
        }
      });

      const currentToc = elem(`.${tocActive}`);

 assets/js/search.js

@@ -7,7 +7,7 @@
  {{ range $index, $page := .Site.Pages }}
  this.add({
    "id": "{{ $index }}",
    "link": "{{ .RelPermalink }}",
    "link": "{{ .Permalink }}",
    "title": "{{ .Title }}",
    "body": "{{ .PlainWords }}",
  });
@@ -18,7 +18,7 @@
  {{ range $index, $page := .Site.Pages }}
   {
     id: {{ $index }},
     link: "{{ .RelPermalink }}",
     link: "{{ .Permalink }}",
     title: "{{ .Title }}",
   },
  {{ end }}

 assets/sass/_components.sass

@@ -21,13 +21,38 @@
  flex: 1
  display: flex
  justify-content: flex-end
  position: relative
  &_field
    padding: 0.5rem 1.5rem
    padding: 0.5rem 1.5rem 0.5rem 2.5rem
    border-radius: 1.5rem
    width: 13.5rem
    outline: none
    border: none
    box-shadow: 0 1rem 4rem rgba(0,0,0,0.17)
    font-size: 1rem
  &_label
    background-image: url(/images/search.svg)
    width: 1.25rem
    height: 1.25rem
    position: absolute
    right: 11.5rem
    top: 0.5rem
    opacity: 0.33
  &_result
    padding: 0.5rem 1rem
    &:hover
      background-color: var(--haze)
    &s
      width: 13.5rem
      background-color: var(--light)
      border-radius: 0 0 0.25rem 0.25rem
      box-shadow: 0 1rem 4rem rgba(0,0,0,0.17)
      position: absolute
      top: 100%
      display: grid
      overflow: hidden
      &:empty
        display: none

.button
  background-color: var(--dark)

 assets/sass/_nav.sass

@@ -4,12 +4,14 @@
  grid-gap: 1rem
  padding: 1rem 1.5rem !important
  align-items: center
  position: fixed
  top: 0
  left: 0
  width: 100%
  background-color: var(--bg)
  z-index: 999999
  &_header
    position: fixed
    top: 0
    left: 0
    width: 100%
    background-color: var(--bg)
    z-index: 999999
  &_body
    display: flex
  &-link

 config.toml

File was deleted

 exampleSite/.gitignore

New file
@@ -0,0 +1,4 @@
public/
resources/
node_modules/
.DS_Store

 exampleSite/.gitmodules

New file
@@ -0,0 +1,3 @@
[submodule "themes/compose"]
    path = themes/compose
    url = https://github.com/onweru/compose

 exampleSite/LICENSE

New file
@@ -0,0 +1,201 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 exampleSite/README.md

New file
@@ -0,0 +1,3 @@
## Guide

This guide is in beta. 

 exampleSite/config.toml

New file
@@ -0,0 +1,48 @@
baseURL = "https://compose-docs.netlify.com/"
title = "Compose Docs"
enableRobotsTXT = true
theme = "compose"
enableGitInfo = true

disableKinds = ["taxonomy", "taxonomyTerm"]

#  menu items
[[menu.main]]
    name = "Docs"
    weight = 2
    url = "/docs/"

[[menu.main]]
    name = "Example"
    weight = 3
    url = "/"

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true
  [markup.highlight]
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineNoStart = 1
    lineNos = true
    lineNumbersInTable = true
    noClasses = false
    style = "monokai"
    tabWidth = 2

# Everything below this are Site Params

[params]
  copyright = "Weru"
  searchPlaceholder = "Search the docs ..."
  repo = "https://github.com/onweru/compose"

  time_format_blog = "Monday, January 02, 2006"
  time_format_default = "January 2, 2006"

  [params.source]
    name = "GitHub"
    icon = "github.svg"
    url = "https://github.com/onweru/compose/"

 exampleSite/content/_index.md

New file
@@ -0,0 +1,25 @@
+++
title = "Compose"
+++

{{< block "grid-2 mt-2" >}}
{{< column >}}

# Compose your Docs with __Ease__.

Compose is a lean theme for the _Hugo_, inspired by [forestry.io](https://forestry.io). 

We do a [Pull Request](https://github.com/onweru/compose/pulls) contributions workflow on **GitHub**. Also feel free to raise any issues or feature suggestions.

Note that the theme is built with simplicity in mind. This way, if a suggestion complicates the usability of the theme, it may be declined. New users are always welcome!

{{< button "/docs/" "Read the Docs" >}} {{< button "https://github.com/onweru/compose" "Download Theme" >}}

{{< /column >}}
{{< column >}}
![diy](/images/diy.jpeg)

<!-- Photo by [Jasmin Schreiber](https://unsplash.com/@lavievagabonde?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on Unsplash -->

{{< /column >}}
{{< /block >}}

 exampleSite/content/docs/_index.md

New file
@@ -0,0 +1,40 @@

---
title: "Compose Docs"
weight: 1
---

Welcome to the Compose theme user guide! This guide shows you how to get started creating technical documentation sites using Compose, including site customization and how to use Compose's blocks and templates.

## What is Compose?

Compose is a theme for the [Hugo](https://gohugo.io/) static site generator that's specifically designed for technical 
documentation sets and has a lot of best practices built in. Use Compose to get a working and reliable documentation 
site up and running fast, and then get back to focusing on great content for your users. 
[Learn more about Compose](/about).

In addition to the theme itself, we provide an [example site](https://github.com/onweru/compose) that uses lots of Compose features and has a useful skeleton site structure (with advice for what to put in it!) for a large technical documentation set. You can copy the entire site and edit it for your own projects, or just explore the site and its source to see what Compose can do. The site you're currently reading also uses Compose and is a useful example of a smaller Compose docset: feel free to copy it or borrow from it if it suits your needs better than the "big" example.

Compose itself does **not** provide:

* **Source hosting and management**: Our theme and site source files live on [GitHub](https://github.com/), which is the simplest approach for most projects. However, you can also keep your project files in [GitLab](https://about.gitlab.com/), [BitBucket](https://bitbucket.org/product), locally, or wherever you like. Be aware that where your source files live may affect the Compose features you can use (such as letting users file documentation issues) and site deployment options.
* **Site deployment**: You can find out about deployment options in [Previews and Deployment](./deployment/). This site uses [Netlify](https://www.netlify.com/). 

Compose also doesn't actually generate your site's HTML files: that's Hugo's job! Hugo takes your Markdown or HTML doc source files and Compose's theme files and builds them into a static site for deployment. You can find out more about Hugo and how it works in the [Hugo documentation](https://gohugo.io/documentation/).

## Is Compose for me?

Compose is particularly useful for medium to large technical documentation sets with 20+ pages of docs and/or multiple types of docs and pages: tutorials, reference documentation, blog posts, community pages, and so on.

If you have a smaller project with only a couple of pages of documentation and hence simpler navigation needs, Compose may be too heavyweight a solution for you. Instead, consider:

* A simpler Hugo or Jekyll theme: find out what's available in Github Pages' [built-in Jekyll options](https://pages.github.com/themes/) and the [Hugo theme gallery](https://themes.gohugo.io/).
* A good README file that tells users what your project does and links to some examples.

If you have a very large documentation project, our example site structure may not be sufficient either, though you can still use our theme, possibly with heavier customization.

If you'd like to use Compose's layouts but prefer to use Jekyll, [vsoch](https://github.com/vsoch) has created a [Compose Jekyll port](https://github.com/vsoch/compose-jekyll) that includes many of Compose's features (though as this is a separate project it won't be automatically updated along with Compose).

## Ready to get started?

Find out how to build and serve your first site in [Getting Started](./getting-started/). Or visit the [example site](https://example.compose.dev) and [its repo](https://github.com/onweru/compose) and start exploring!

 exampleSite/content/docs/customization/_index.md

New file
@@ -0,0 +1,12 @@
---
title: "Customization"
weight: 3
description: >
  How to add content to and customize your Docsy site.
---

## Content root directory

You add content for your site under the **content root directory** of your Hugo site project - either `content/` or a [language-specific](/docs/language/) root like `content/en/`. The main exception here is static files that you don't want built into your site: you can find out more about where you add these below in [Adding static content](#adding-static-content). The files in your content root directory are typically grouped in subdirectories corresponding to your site's sections and templates, which we'll look at in [Content sections and templates](#content-sections-and-templates).

You can find out more about Hugo directory structure in [Directory Structure Explained](https://gohugo.io/getting-started/directory-structure/#directory-structure-explained).

 exampleSite/content/docs/customization/logos and images.md

New file
@@ -0,0 +1,16 @@
---
title: "Logos and Images"
weight: 5
description: >
  Add and customize logos, icons, and images in your project.
---

## Add your logo

Add your project logo as `assets/images/logo.svg` in your project. This overrides the default compose logo in the theme. If you don't want a project logo, set `navbar_logo` to `false` (or delete the variable) in your `config.toml`:

```
navbar_logo = false
```

If you decide at a later stage that you'd like to add a logo to your navbar, you can set the parameter to `true`:

 exampleSite/content/docs/customization/shortcodes/index.md

New file
@@ -0,0 +1,66 @@
---
title: "Shortcodes"
weight: 4
description: >
  Use hugo shortcodes to quickly compose site pages.
---

Rather than writing all your site pages from scratch, Hugo lets you define and use [shortcodes](https://gohugo.io/content-management/shortcodes/). These are reusable snippets of content that you can include in your pages, often using HTML to create effects that are difficult or impossible to do in simple Markdown. Shortcodes can also have parameters that let you, for example, add your own text to a fancy shortcode text box. As well as Hugo's [built-in shortcodes](https://gohugo.io/content-management/shortcodes/), Compose provides some shortcodes of its own to help you build your pages.

Why shortcodes? While markdown is sufficient to produce simple pages, it's insufficient where complex page structures are needed. Thusly, whenever we need special styling, shortcodes compliment the shortcomings of markdown.

Shortcodes use either `` or `` as the *opening tags*. The former are used if the immediate content is markdown, while the latter is used whenever the immediate content is something else. 

Sometimes, the shortcode will wrap content, sometimes it won't. When content is wrapped, a closing shortcode tag is needed. Please see the link I provided above and the markdown files for examples. You'll get the gist pretty quickly.

I've setup the following shortcodes:

### Block 

Takes positional modifiers

**Example**
```markdown
...
  {{</* block "modifiers" */>}}
  <!-- Nest columns or content  -->
  {{</* /block */>}}
...
```

### Column

It takes positional parameters

**Example**
```markdown
  {{</* column "mt-2 mb-2" */>}}
  <!-- applied margin top and margin bottom modifiers -->
  {{</* /column */>}}
```

### Video

This allows you to embed a youtube video in you content. You would achieve that using a positional parameter (needs no name )parameter, like so:

**Example:**

```markdown
  {{</* youtube "xWF59rWSceA" */>}}
  <!-- Use the youtube video id -->
```

### Button

This adds a styled link (styled like a button). It takes two no-optional parameters:

| PARAMETER | PURPOSE | OPTIONAL |
| :---  | :--- | :--- |
| label | button text | no |
| url | button link | no |

**Example**

```
  {{</* button url="/" label="doe nu mee" */>}}
```

 exampleSite/content/docs/customization/shortcodes/spruce.jpg

 exampleSite/content/docs/getting started/_index.md

New file
@@ -0,0 +1,17 @@
---
title: "Getting Started"
weight: 2
description: >
  This page tells you how to get started with the Compose theme, including installation and basic configuration.
---

## Prerequisites and installation

### Install Hugo 

You need a [recent **extended** version](https://github.com/gohugoio/hugo/releases) (we recommend version 0.61 or later) of [Hugo](https://gohugo.io/) to do local builds and previews of sites (like this one) that uses this theme.

If you install from the release page, make sure to get the `extended` Hugo version, which supports [sass](https://sass-lang.com/documentation/file.SCSS_FOR_SASS_USERS.html); you may need to scroll down the list of releases to see it. 

For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/).


 exampleSite/netlify.toml

New file
@@ -0,0 +1,30 @@
[build]
publish = "public"
command = "hugo --gc --minify"

[context.production.environment]
HUGO_VERSION = "0.64.0"
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"

[context.split1]
command = "hugo --gc --minify --enableGitInfo"

[context.split1.environment]
HUGO_VERSION = "0.64.0"
HUGO_ENV = "production"

[context.deploy-preview]
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"

[context.deploy-preview.environment]
HUGO_VERSION = "0.64.0"

[context.branch-deploy]
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"

[context.branch-deploy.environment]
HUGO_VERSION = "0.64.0"

[context.next.environment]
HUGO_ENABLEGITINFO = "true"

 exampleSite/resources/_gen/assets/sass/sass/main.sass_ca26857cefa9076967ab300682271513.content

New file
@@ -0,0 +1,3 @@
html{--light: #fff;--dark: #010101;--haze: #f2f5f2;--bubble: #111;--accent: var(--gray);--bg: var(--light);--text: var(--dark);--theme: #20c997;--font: 'Metropolis', sans-serif}*{box-sizing:border-box;-webkit-appearance:none;margin:0;padding:0}body,html{scroll-behavior:smooth}body{font-family:var(--font);background-color:var(--bg);color:var(--text);font-size:16px;line-height:1.5;max-width:1440px;margin:0 auto;position:relative;font-kerning:normal;display:flex;flex-direction:column;justify-content:space-between;min-height:100vh;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}a{text-decoration:none;color:inherit}p{padding:1rem 0}li{padding:0.25rem 0}li p{padding:0.5rem 0}blockquote{opacity:0.8;padding:1rem;position:relative;quotes:"“" "”" "‘" "’";margin:0.75rem 0;display:flex;flex-flow:row wrap;background-repeat:no-repeat;background-size:5rem;background-position:50% 50%;position:relative}blockquote::before{content:"";padding:1px;position:absolute;top:0;bottom:0;left:0;background:var(--theme)}blockquote p{padding-left:0.5rem 0 !important;font-size:1.1rem !important;width:100%;font-weight:300;font-style:italic}h1,h2,h3,h4,h5{font-family:inherit;font-weight:500;padding:0.33rem 0;color:inherit;line-height:1.35}h1{font-size:200%}h2{font-size:175%}h3{font-size:150%}h4{font-size:125%}h5{font-size:120%}h6{font-size:100%}img,svg,figure{max-width:100%;vertical-align:middle}img{height:auto;margin:1rem auto;padding:0}main{padding-bottom:45px;flex:1}ol,ul{list-style:none}b,strong{font-weight:500}hr{border:none;padding:0.5px;background:var(--text);opacity:0.5;margin:1rem 0}aside{position:sticky;top:7rem}aside h3{position:relative}aside ul{padding:0;list-style:none}th,td{padding:0.5rem;font-weight:400 !important}th:not(:first-child),td:not(:first-child){padding-left:1.5rem}thead{background:var(--theme);color:var(--light);font-weight:400;text-align:left}tbody tr:nth-child(even){background-color:var(--gray);box-shadow:0 1rem 0.75rem -0.75rem rgba(0,0,0,0.07)}table{margin:1.5rem 0;width:100%}.main{flex:1}.page-home h1{font-weight:300}.pager{display:flex;justify-content:space-between;margin:2.5rem 0}.content ul,.content ol{padding-left:1.1rem}.content ul{list-style:initial}.content ol{list-style:decimal}::placeholder{font-size:1rem}.nav{display:grid;grid-template-columns:10rem 1fr 1fr;grid-gap:1rem;padding:1rem 1.5rem !important;align-items:center;background-color:var(--bg)}.nav_header{position:fixed;top:0;left:0;width:100%;background-color:var(--bg);z-index:999999}.nav_body{display:flex}.nav-link{display:inline-flex;padding:0.5rem 1rem}.section_title{font-size:1.1rem}.section_link{font-size:1rem;font-weight:400}.sidebar-link{display:grid;padding:0.2rem 0}.toc{border-left:2px solid var(--theme);padding:0 1rem;height:0;overflow:hidden}.toc_active{height:initial}.search{flex:1;display:flex;justify-content:flex-end;position:relative}.search_field{padding:0.5rem 1.5rem 0.5rem 2.5rem;border-radius:1.5rem;width:13.5rem;outline:none;border:none;box-shadow:0 1rem 4rem rgba(0,0,0,0.17);font-size:1rem}.search_label{background-image:url(/images/search.svg);width:1.25rem;height:1.25rem;position:absolute;right:11.5rem;top:0.5rem;opacity:0.33}.search_result{padding:0.5rem 1rem}.search_result:hover{background-color:var(--haze)}.search_results{width:13.5rem;background-color:var(--light);border-radius:0 0 0.25rem 0.25rem;box-shadow:0 1rem 4rem rgba(0,0,0,0.17);position:absolute;top:100%;display:grid;overflow:hidden}.search_results:empty{display:none}.button{background-color:var(--dark);color:var(--light);border-radius:0.25rem;display:inline-grid;padding:0.75rem 1.5rem;text-align:center}.button:hover{opacity:0.84}.button+.button{background-color:var(--haze);color:var(--dark)}@media screen and (min-width: 20rem){.button+.button{margin-left:0.5rem}}.wrap{max-width:1240px}.wrap,.wrap{width:100%;padding:0 25px;margin:0 auto}.pt-1{padding-top:1.5rem}.pb-1{padding-bottom:1.5rem}.mt-1{margin-top:1.5rem}.mb-1{margin-bottom:1.5rem}.pt-2{padding-top:3rem}.pb-2{padding-bottom:3rem}.mt-2{margin-top:3rem}.mb-2{margin-bottom:3rem}.pt-3{padding-top:4.5rem}.pb-3{padding-bottom:4.5rem}.mt-3{margin-top:4.5rem}.mb-3{margin-bottom:4.5rem}.pt-4{padding-top:6rem}.pb-4{padding-bottom:6rem}.mt-4{margin-top:6rem}.mb-4{margin-bottom:6rem}.grid-2,.grid-3,.grid-4,.grid-auto,.grid-reverse{display:grid;grid-template-columns:1fr}[class*='grid-']{grid-gap:2rem}@media screen and (min-width: 42rem){.grid-auto{grid-template-columns:2fr 5fr}.grid-reverse{grid-template-columns:3fr 1fr}.grid-2{grid-template-columns:1fr 1fr}.grid-3{grid-template-columns:repeat(auto-fit, minmax(19rem, 1fr))}.grid-4{grid-template-columns:repeat(auto-fit, minmax(16rem, 1fr))}}.active{color:var(--theme)}code{min-width:100%;max-width:100%}pre{display:grid;padding:1rem;overflow-x:auto}.highlight{display:grid;margin:1.25rem 0;box-shadow:0 0 2.5rem rgba(0,0,0,0.12);border-radius:4px;overflow:hidden}.highlight table{margin:0;border-collapse:collapse}.highlight .highlight{margin:0}.lntd:first-child{width:2.75rem;background-color:var(--theme);color:var(--light)}.lntd:first-child pre{padding:0}.lntd:first-child code{display:flex;flex-flow:column;align-items:center}.lntd:last-child{padding-left:0}footer{min-height:150px}

/*# sourceMappingURL=styles.css.map */

 exampleSite/resources/_gen/assets/sass/sass/main.sass_ca26857cefa9076967ab300682271513.json

New file
@@ -0,0 +1 @@
{"Target":"css/styles.364ead8cdf7be90c89dc92e65b6115713a262d145ca51c6e3a4519ed1578b2b9637162aeccd6cf9af5c5e83da4ca19cd271ca3c5e4acaf8768a00e8909c07076.css","MediaType":"text/css","Data":{"Integrity":"sha512-Nk6tjN976QyJ3JLmW2EVcTomLRRcpRxuOkUZ7RV4srljcWKuzNbPmvXF6D2kyhnNJxyjxeSsr4dooA6JCcBwdg=="}}

 exampleSite/resources/_gen/images/about/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_1920x1080_fill_q75_box_smart1.jpg

 exampleSite/resources/_gen/images/about/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_1920x1080_fill_q75_catmullrom_smart1.jpg

 exampleSite/resources/_gen/images/about/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_960x540_fill_q75_box_smart1.jpg

 exampleSite/resources/_gen/images/about/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_960x540_fill_q75_catmullrom_smart1.jpg

 exampleSite/resources/_gen/images/docs/Adding content/Shortcodes/spruce_hu0fa7d855ef6295d2886abf8df96c5044_124081_400x450_fill_q75_box_smart1.jpg

 exampleSite/resources/_gen/images/docs/Adding content/Shortcodes/spruce_hu0fa7d855ef6295d2886abf8df96c5044_124081_400x450_fill_q75_catmullrom_smart1.jpg

 exampleSite/resources/_gen/images/en/about/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_1920x1080_fill_q75_catmullrom_smart1.jpg

 exampleSite/resources/_gen/images/en/about/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_960x540_fill_q75_catmullrom_smart1.jpg

 exampleSite/resources/_gen/images/en/docs/Adding content/Shortcodes/spruce_hu0fa7d855ef6295d2886abf8df96c5044_124081_400x450_fill_q75_catmullrom_smart1.jpg

 exampleSite/resources/_gen/images/en/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_1920x1080_fill_q75_catmullrom_top.jpg

 exampleSite/resources/_gen/images/en/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_960x540_fill_q75_catmullrom_top.jpg

 exampleSite/resources/_gen/images/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_1920x1080_fill_q75_catmullrom_top.jpg

 exampleSite/resources/_gen/images/featured-background_huecd58d056379c142f106ffb096c7e70a_221334_960x540_fill_q75_catmullrom_top.jpg

 exampleSite/static/images/diy-2.jpeg

Binary files differ

 exampleSite/static/images/diy.jpeg

Binary files differ

 images/.gitkeep

 images/screenshot.png

 images/tn.png

 layouts/404.html

@@ -1,8 +1,6 @@
{{- define "main"}}
<main id="main">
  <div>
    <h1 id="title">Not found</h1>
    <p>Oops! This page doesn't exist. Try going back to our <a href="{{ "/" | relURL }}">home page</a>.</p>
  </div>
<main>
  <h1 id="title">Not found</h1>
  <p>Bummer! This page doesn't exist. Y<a href="{{ .Site.BaseURL }}">back home</a>.</p>
</main>
{{- end }}

 layouts/_default/baseof.html

@@ -4,12 +4,12 @@
  {{- partial "head.html" . }}
</head>
<body class="page-{{ .Kind }}">
  <header>
  <header class="nav_header">
    {{- partial "nav.html" . }}
  </header>
  <main class="main wrap pt-4">
    {{- if eq .Section "docs" }}
    {{- partial "docs.html" . }}
    {{- partial "document.html" . }}
    {{- else }}
    {{- block "main" . }}{{ end }}
    {{- end }}

 layouts/partials/breadcrumb.html

File was deleted

 layouts/partials/docs.html

File was deleted

 layouts/partials/document.html

New file
@@ -0,0 +1,16 @@
<div class="grid-auto">
  <div>
    {{- partial "sidebar.html" . }}
  </div>
  <div class="content">
    {{- .Content }}
    <div class="pager">
      {{- with .Prev }}
      <a href="{{ .Permalink }}" id="prev">{{ .Title }}</a>
      {{ end }}
      {{- with .Next }}
      <a href="{{ .Permalink }}" id="next">{{ .Title }}</a>
      {{- end }}
    </div>
  </div>
</div>

 layouts/partials/favicons.html

File was deleted

 layouts/partials/footer.html

@@ -1,9 +1,5 @@
{{- $links := .Site.Params.links }}
<footer class="mt-2 pt-2 pb-2">
  <div class="wrap">
    <div class="">
      {{- with .Site.Params.copyright }}<small class="">&copy; {{ now.Year}} {{ .}} {{ T "footer_all_rights_reserved" }}</small>{{ end }}
      {{ with .Site.Params.privacy_policy }}<small class=""><a href="{{ . }}" target="_blank">{{ T "footer_privacy_policy" }}</a></small>{{ end }}
    </div>
    <p>&copy; {{ now.Year}} {{ .Site.Params.author }}</p>
  </div>
</footer>

 layouts/partials/head.html

@@ -1,15 +1,20 @@
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="viewport" content="width=device-width, initial-scale=1">
{{- hugo.Generator }}
{{- partial "favicons.html" . }}
{{- $iconsPath := "/favicons/" }}
<link rel="apple-touch-icon" sizes="180x180" href='{{ absURL (printf "%sapple-touch-icon.png" $iconsPath) }}'>
<link rel="icon" type="image/png" sizes="32x32" href='{{ absURL (printf "%sfavicon-32x32.png" $iconsPath) }}'>
<link rel="icon" type="image/png" sizes="16x16" href='{{ absURL (printf "%sfavicon-16x16.png" $iconsPath) }}'>
<link rel="manifest" href='{{ absURL (printf "%ssite.webmanifest" $iconsPath) }}'>
<link rel="mask-icon" href='{{ absURL (printf "%ssafari-pinned-tab.svg" $iconsPath) }}'  color="#004750">
<link rel="shortcut icon" href='{{ absURL (printf "%sfavicon.ico" $iconsPath) }}'>
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-config" content='{{ absURL (printf "%sbrowserconfig.xml" $iconsPath) }}'>
<meta name="theme-color" content="#ffffff">

<title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title>
{{- template "_internal/opengraph.html" . -}}
{{- template "_internal/google_news.html" . -}}
{{- template "_internal/schema.html" . -}}
{{- template "_internal/twitter_cards.html" . -}}
{{- if eq (getenv "HUGO_ENV") "production" }}
{{- template "_internal/google_analytics_async.html" . }}
{{- end }}

{{- partial "opengraph.html" . }}

{{- $options := (dict "targetPath" "css/styles.css" "outputStyle" "compressed" "enableSourceMap" "true") -}}
{{- $styles := resources.Get "sass/main.sass" | resources.ExecuteAsTemplate "main.sass" . | resources.ToCSS $options | resources.Fingerprint "sha512" }}

 layouts/partials/nav.html

@@ -1,5 +1,5 @@
<nav class="wrap nav">
    <a class="navbar-brand" href="{{ .Site.Home.RelPermalink }}"><img src = "/images/compose.svg"></span>
    <a class="navbar-brand" href="{{ .Site.BaseURL }}"><img src='{{ absURL "/images/compose.svg" }}'></span>
    </a>
    {{- partial "search.html" . }}
    <ul class="nav_body">
@@ -11,9 +11,13 @@
            {{- $active = or $active ( $.IsDescendant .)  }}
            {{- end }}
            {{- $url := urls.Parse .URL }}
            {{- $baseurl := urls.Parse $.Site.Params.Baseurl }}
            <a class="nav-link{{if $active }} active{{end}}" href="{{ with .Page }}{{ .RelPermalink }}{{ else }}{{ .URL | relLangURL }}{{ end }}" {{ if ne $url.Host $baseurl.Host }}target="_blank" {{ end }}><span{{if $active }} class="active"{{end}}>{{ .Name }}</span></a>
            {{- $baseurl := $.Site.BaseURL }}
            <a class="nav-link{{if $active }} active{{end}}" href="{{ with .Page }}{{ $baseurl }}{{ .Permalink }}{{ else }}{{ $baseurl }}{{ .URL }}{{ end }}"><span{{if $active }} class="active"{{end}}>{{ .Name }}</span></a>
        </li>
        {{- end }}
        {{ $repo := .Site.Params.source }}
        <li class="nav-item">
            <a class="nav-link" href="{{ $repo.url }}" target="_blank">{{ $repo.name }}</a>
        </li>
    </ul>
</nav>

 layouts/partials/opengraph.html

New file
@@ -0,0 +1,6 @@
{{- template "_internal/opengraph.html" . -}}
{{- template "_internal/schema.html" . -}}
{{- template "_internal/twitter_cards.html" . -}}
{{- if eq (getenv "HUGO_ENV") "production" }}
{{- template "_internal/google_analytics_async.html" . }}
{{- end }}

 layouts/partials/scripts.html

@@ -4,7 +4,6 @@
{{- $searchPath := "js/search.js" }}
{{- $search := resources.Get $searchPath | resources.ExecuteAsTemplate $searchPath . }}


{{- $mainScriptPath := "js/index.js" }}
{{- $main := resources.Get $mainScriptPath | resources.ExecuteAsTemplate $mainScriptPath . }}


 layouts/partials/search.html

@@ -1,6 +1,6 @@
<div class="search">
  <label for="search" class="search_label"></label>
  <input type="search" class="search_field" placeholder="Search" id="search">
  <input type="search" class="search_field" placeholder="{{ .Site.Params.searchPlaceholder }}" id="search">
  <div class="search_results"></div>
</div>


 layouts/partials/section-index.html

File was deleted

 layouts/partials/sidebar.html

@@ -1,20 +1,20 @@
<aside class="aside">
  {{- template "tree" (dict "page" . "section" .FirstSection)  }}
  {{- define "tree" }}
  {{- $s := .section }}
  {{- $p := .page }}
  {{- $permalink := $p.RelPermalink }}
  {{- $section := .section }}
  {{- $page := .page }}
  {{- $permalink := $page.RelPermalink }}
  <section class="section">
    <h2 class="section_title{{ if eq $s.RelPermalink $permalink }} active{{ end }}"><a  href="{{ $s.RelPermalink }}" class="group">{{ $s.Title }}</a></h2>
      {{- $pages := $s.Pages }}
    <h2 class="section_title{{ if eq $section.RelPermalink $permalink }} active{{ end }}"><a  href="{{ $section.Permalink }}" class="group">{{ $section.Title }}</a></h2>
      {{- $pages := $section.Pages }}
      {{- with $pages }}
      <section class="" id="docs-{{ anchorize $s.Title }}">
      <section class="" id="docs-{{ anchorize $section.Title }}">
        {{- range . }}
        {{- if .IsPage }}
        <h3 class="section_link{{ if eq .RelPermalink $permalink }} active{{ end }}"><a id="docs-{{ anchorize .Title }}" href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
        <h3 class="section_link{{ if eq .RelPermalink $permalink }} active{{ end }}"><a id="docs-{{ anchorize .Title }}" href="{{ .Permalink }}">{{ .Title }}</a></h3>
        {{- .TableOfContents }}
        {{- else }}
        {{- template "tree" (dict "page" $p "section" .) }}
        {{- template "tree" (dict "page" $page "section" .) }}
        {{- end }}
        {{- end }}
      </section>

 layouts/shortcodes/alert.html

File was deleted

 layouts/shortcodes/readfile.html

File was deleted

 layouts/shortcodes/underline.html

File was deleted

 static/images/github.svg

New file
@@ -0,0 +1 @@
<svg enable-background="new 0 0 24 24" height="512" viewBox="0 0 24 24" width="512" xmlns="http://www.w3.org/2000/svg"><path d="m12 .5c-6.63 0-12 5.28-12 11.792 0 5.211 3.438 9.63 8.205 11.188.6.111.82-.254.82-.567 0-.28-.01-1.022-.015-2.005-3.338.711-4.042-1.582-4.042-1.582-.546-1.361-1.335-1.725-1.335-1.725-1.087-.731.084-.716.084-.716 1.205.082 1.838 1.215 1.838 1.215 1.07 1.803 2.809 1.282 3.495.981.108-.763.417-1.282.76-1.577-2.665-.295-5.466-1.309-5.466-5.827 0-1.287.465-2.339 1.235-3.164-.135-.298-.54-1.497.105-3.121 0 0 1.005-.316 3.3 1.209.96-.262 1.98-.392 3-.398 1.02.006 2.04.136 3 .398 2.28-1.525 3.285-1.209 3.285-1.209.645 1.624.24 2.823.12 3.121.765.825 1.23 1.877 1.23 3.164 0 4.53-2.805 5.527-5.475 5.817.42.354.81 1.077.81 2.182 0 1.578-.015 2.846-.015 3.229 0 .309.21.678.825.56 4.801-1.548 8.236-5.97 8.236-11.173 0-6.512-5.373-11.792-12-11.792z" fill="#212121"/></svg>

 static/images/search.svg

New file
@@ -0,0 +1,43 @@
<?xml version="1.0" encoding="iso-8859-1"?>

<!-- Generator: Adobe Illustrator 19.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->

<svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"

     viewBox="0 0 511.999 511.999" style="enable-background:new 0 0 511.999 511.999;" xml:space="preserve">

<g>

    <g>

        <path d="M508.874,478.708L360.142,329.976c28.21-34.827,45.191-79.103,45.191-127.309c0-111.75-90.917-202.667-202.667-202.667

            S0,90.917,0,202.667s90.917,202.667,202.667,202.667c48.206,0,92.482-16.982,127.309-45.191l148.732,148.732

            c4.167,4.165,10.919,4.165,15.086,0l15.081-15.082C513.04,489.627,513.04,482.873,508.874,478.708z M202.667,362.667

            c-88.229,0-160-71.771-160-160s71.771-160,160-160s160,71.771,160,160S290.896,362.667,202.667,362.667z"/>

    </g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

<g>

</g>

</svg>


 theme.toml

@@ -1,12 +1,12 @@
name = "Compose"
license = "MIT"
licenselink = "https://github.com/google/compose/blob/master/LICENSE"
description = "A Hugo theme for technical documentation sites"
homepage = "https://compose.netlify.com"
tags = ["documentation", "simple", "customizable", "responsive", "docs"]
features = []
min_version = 0.53
licenselink = "https://github.com/onweru/compose/blob/master/LICENSE"
description = "A hugo docs theme inspired by forestry.io's docs page"
homepage = "https://compose-docs.netlify.com"
tags = ["simple", "docs"]
features = ["docs", "search"]
min_version = 0.61

[author]
  name = "Weru"
  homepage = "https://compose.netlify.com"
  homepage = "https://github.com/onweru"