update

weru

05.38.2020 48bcd3ffcacf822308adb371073864cb2b06f4a8

update

 exampleSite/config.toml

@@ -12,11 +12,6 @@
    weight = 2
    url = "/docs/"

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

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
@@ -35,7 +30,7 @@
# Everything below this are Site Params

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


 exampleSite/content/docs/_index.md

@@ -5,36 +5,3 @@
---

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

File was deleted

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

File was deleted

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

Binary files differ

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

New file
@@ -0,0 +1,12 @@
---
title: "Overview"
weight: 4
description: >
  Use hugo shortcodes to quickly compose your documentation pages.
---

Instead of writing all your site pages from scratch, Hugo lets you define and use [shortcodes](https://gohugo.io/content-management/shortcodes/). 

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.

This way, you can side step complex html and css boilerplate in your content files.

 exampleSite/content/docs/getting started/shortcodes/index.md

File was renamed from exampleSite/content/docs/customization/shortcodes/index.md
@@ -1,19 +1,14 @@
---
title: "Shortcodes"
weight: 7
weight: 5
description: >
  Use hugo shortcodes to quickly compose site pages.
resources:
- src: "**spruce*.jpg"
  params:
    byline: "Photo: Bjørn Erik Pedersen / CC-BY-SA"
---

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. 
This way, you can side step complex html and css boilerplate in your content files. 

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.