diff options
| author | vjeantet <valere.jeantet@gmail.com> | 2020-08-30 19:15:15 +0300 |
|---|---|---|
| committer | vjeantet <valere.jeantet@gmail.com> | 2020-08-30 19:15:15 +0300 |
| commit | c08d263aeedf0470c02d7a6c88000c108412316f (patch) | |
| tree | e290e5ead116049aa172f1019b4e99e9c58aed89 | |
| parent | 84dc97cffaded0a1ce61ba0cebbc3334dd082b70 (diff) | |
update documentation
74 files changed, 824 insertions, 670 deletions
diff --git a/assets/sass/main.scss b/assets/sass/main.scss index 9827b5e..48b1235 100644 --- a/assets/sass/main.scss +++ b/assets/sass/main.scss @@ -248,6 +248,7 @@ article section.page { top: 45px;
background-color: inherit;
+
flex: 1;
display: flex;
diff --git a/exampleSite/config-template.toml b/exampleSite/config-template.toml new file mode 100644 index 0000000..5c7d634 --- /dev/null +++ b/exampleSite/config-template.toml @@ -0,0 +1,69 @@ +title = "DocPort Documentation" + +theme = "hugo-theme-docport" + +baseURL = "https://example.com" + +languageCode = "en-us" +DefaultContentLanguage = "en" +pygmentsCodeFences = true +pygmentsStyle = "monokai" + +defaultContentLanguageInSubdir= false +enableMissingTranslationPlaceholders = false + +# Keep this as is +[outputs] +home = [ "HTML", "RSS", "JSON"] + +# Site params +[params] +ordersectionsby = "weight" # ordersectionsby = "title" +#color_main = "#737373" +#color_second = "#b30000" +disableSearch = false # default is false +disableNavChevron = false # set true to hide next/prev chevron, default is false +menushortcutsnewtab = false # set true to open shortcuts links to a new tab/window + +editURL = "https://github.com/vjeantet/hugo-theme-docport/edit/master/exampleSite/content/" +enableGitInfo = true + +[markup.goldmark.renderer] +unsafe = true + +# Code highlight configuration +[markup.highlight] +codeFences = true +guessSyntax = true +hl_Lines = "" +lineNoStart = 1 +lineNos = false +lineNumbersInTable = true +noClasses = true +style = "monokai" +tabWidth = 2 + +# +# top menu shotcuts +# +[[menu.shortcuts]] +name = "Github" +identifier = "ds" +url = "https://github.com/vjeantet/hugo-theme-docport" +weight = 10 + +[[menu.shortcuts]] +name = "Download" +url = "https://github.com/vjeantet/hugo-theme-docport/archive/master.zip" +weight = 11 + +[[menu.shortcuts]] +name = "Hugo Documentation" +identifier = "hugodoc" +url = "https://gohugo.io/" +weight = 20 + +[[menu.shortcuts]] +name = "Credits" +url = "/docport-theme/credits/" +weight = 30
\ No newline at end of file diff --git a/exampleSite/content/content-and-customization/00-adding-content/_index.md b/exampleSite/content/content-and-customization/00-adding-content/_index.md new file mode 100644 index 0000000..a9cba7c --- /dev/null +++ b/exampleSite/content/content-and-customization/00-adding-content/_index.md @@ -0,0 +1,102 @@ +--- +lastmodifierdisplayname: Valere JEANTET +title: Adding content +description: This page tells you how to use the theme to add and structure your site content. + +date: 2017-04-24T18:36:24+02:00 +layout: "" +hidden: false +head: "" +creatordisplayname: Valere JEANTET +pre: "" +lastmodifieremail: valere.jeantet@gmail.com +creatoremail: valere.jeantet@gmail.com +weight: 1 +tags: + - tag1 + - tag2 +--- + +{{% notice %}}This page tells you how to use the theme to add and structure your site content.{{% /notice %}} + + +## Content root directory +You add content for your site under the `content` root directory of your Hugo site project. +The files in your content root directory are typically grouped in subdirectories corresponding to your site’s sections. + +We’ll look at in the following chapter. + +## Content sections +With docport, **Each content page composes the site and navigation structure**, they shape the structure of your website. + +Create a folder for each section and their sub sections, and a `_index.md` in each folder which will act as the section's content. +{{%notice%}}You can add any other page.md in section folder, they will be treated as "[subpages]({{< ref "#subpages" >}})"{{%/notice%}} + + +To link pages to each other, place them in a folders hierarchy. + +```text + content + └── section-one/ + ├── _index.md + └── section-one-two/ + ├── _index.md + ├── section-one-two-three-A/ + │ ├── _index.md + └── section-one-two-three-B/ + ├── _index.md <-- section's page + ├── pageA.md <-- "subpages" + └── pageB.md <-- "subpages" + +``` + +## Subpages +Subpages are contents which belong to the section, and are displayed bellow section's title in the page. \ +Subpages are not displayed in left menu. + +If you look at the current page title, you will see 3 links which reference its 3 subpages. + + + +## Page frontmatter +Each page file in a Hugo site has metadata frontmatter that tells Hugo about the page. You specify page frontmatter in TOML, YAML, or JSON. \ +Use the frontmatter to specify the page title, description, creation date, link title, template, menu weighting, and even any resources such as images used by the page. You can see a complete list of possible page frontmatter in [Front Matter](https://gohugo.io/content-management/front-matter/). + +On top of the [existing ones](https://gohugo.io/content-management/front-matter/), DocPort comes with additional params to control what and how to display your content, their entry in left menu or behaviour. + +```toml ++++ + title="Adding content" + + # order sections + weight=10 + + # Hide some theme components + hide_header=false # set true to hide site header + hide_nav=false # set true to hide the left navigation menu + hide_breadcrumb=false # set true to hide the breadcrumb + hide_toc=false # set true to hide the right menu (table of contents) + hide_footer=false #set true to hide the website footer + + # subpage + subpage = false # usefull when you want to force a sub section to be considered as a subpage + + # Redirect to another content + # Set a full URL or a .md path + # examples : + # redirect = "https://github.com/vjeantet" + # redirect = "folder" + # redirect = "folder/_index.md" + redirect = "folder/_index.md" + ++++ +``` + +{{%alert success%}}More frontmatter params exists to control how to display you content in the navigation, see [Navigation & Search]({{%relref "02-navigation-search" %}}) in the left menu.{{%/alert%}} + +* render page as a slidedeck +* + + + + diff --git a/exampleSite/content/create-page/myslide/index.md b/exampleSite/content/content-and-customization/00-adding-content/myslide/index.md index 1f611bc..1f611bc 100644 --- a/exampleSite/content/create-page/myslide/index.md +++ b/exampleSite/content/content-and-customization/00-adding-content/myslide/index.md diff --git a/exampleSite/content/content-and-customization/00-adding-content/page-images/_index.md b/exampleSite/content/content-and-customization/00-adding-content/page-images/_index.md new file mode 100644 index 0000000..3100ffb --- /dev/null +++ b/exampleSite/content/content-and-customization/00-adding-content/page-images/_index.md @@ -0,0 +1,31 @@ ++++ +title = "images" +date = "2017-04-24T18:36:24+02:00" +weight = 10 +hidden = false +subpage = true ++++ + +Images have a similar syntax to markdown links but include a preceding exclamation point. +``` +  +``` + + +## Resizing image + +Add HTTP parameters `width` and/or `height` to the link image to resize the image. Values are CSS values (default is `auto`). + +``` +  +``` + + + +## Add CSS classes + +Add a HTTP `classes` parameter to the link image to add CSS classes. `shadow` and `border` are available but you could define other ones. +``` +  +``` + diff --git a/exampleSite/content/content-and-customization/00-adding-content/page-images/image.jpeg b/exampleSite/content/content-and-customization/00-adding-content/page-images/image.jpeg Binary files differnew file mode 100644 index 0000000..08f2e1d --- /dev/null +++ b/exampleSite/content/content-and-customization/00-adding-content/page-images/image.jpeg diff --git a/exampleSite/content/create-page/page-slide/_index.md b/exampleSite/content/content-and-customization/00-adding-content/page-slide/_index.md index b5cfbc2..957118c 100644 --- a/exampleSite/content/create-page/page-slide/_index.md +++ b/exampleSite/content/content-and-customization/00-adding-content/page-slide/_index.md @@ -3,7 +3,7 @@ title = "As a SlideDeck" description = "" date = "2017-04-24T18:36:24+02:00" weight = 90 -subpage = true + hide_header=false hide_nav=false @@ -16,13 +16,13 @@ hide_footer=false A basic .md file can be rendered as a reveal.js presentation full screen. {{% notice %}} -**Page As a SlideDeck** is a page that use the full screen to display its markdown content as a [reveals.js presentation](http://lab.hakim.se/reveal-js/). +**A page rendered as a SlideDeck** is a page that use the full screen to display its markdown content as a [reveals.js presentation](http://lab.hakim.se/reveal-js/). \ [{{%icon aspect_ratio%}} click here to view an example]({{%relref "myslide.md"%}}) {{%/notice%}} -To tell Hugo-theme-docport to consider a page as a slide, just add a `type="slide"`in then frontmatter of your file. +To tell Hugo to consider a page as a slidedeck, just add a `type="slide"`in then frontmatter of your page. ```toml +++ diff --git a/exampleSite/content/content-organisation/subpages.png b/exampleSite/content/content-and-customization/00-adding-content/subpages.png Binary files differindex 528b828..528b828 100644 --- a/exampleSite/content/content-organisation/subpages.png +++ b/exampleSite/content/content-and-customization/00-adding-content/subpages.png diff --git a/exampleSite/content/content-and-customization/01-homepage/_index.md b/exampleSite/content/content-and-customization/01-homepage/_index.md new file mode 100644 index 0000000..41c45d3 --- /dev/null +++ b/exampleSite/content/content-and-customization/01-homepage/_index.md @@ -0,0 +1,43 @@ ++++ +title="Home page" +description = "Control how the home page should be rendered" +weight=10 ++++ + +{{% alert theme="success" %}}By default, this theme use the first section (folder) available in your content folder as a homepage.{{%/alert%}} + +## Create a dedicated homepage +Create a `_index.md` in `content` root folder. + +```text + content + ├── _index.md <-- if this file exists, it is the landing page + └── section-one/ <-- else this section will be the home page + +``` + +## Landing page appearance +Remove navigation components from your landing page by setting options in its page frontmatter. You will be able to hide header, breadcrum, toc or footer... +* see hide_xxxx options [here]({{%relref "00-adding-content#page-frontmatter"%}}) +* see [examples of pages]({{%relref "/examples"%}}) rendered with theses options + +{{%notice success%}} +**Nothing but my content !** +\ +set `layout="raw"` in your home page frontmatter : only your content will be rendered, without menu, toc, headers, etc..... [example]({{%relref "/examples/page with raw content"%}}) +{{%/notice%}} + +## Use plain HTML for your homepage +Remember that hugo allows you to write your content with HTML when markdown if not enough. very usefull for a landing page ! + +Example +```toml ++++ +title="Homepage" +layout="raw" ++++ +<div class="myHome"> + Hello +</div> +``` + diff --git a/exampleSite/content/content-and-customization/02-navigation-search/_index.md b/exampleSite/content/content-and-customization/02-navigation-search/_index.md new file mode 100644 index 0000000..e8b0d00 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/_index.md @@ -0,0 +1,17 @@ ++++ +title = "Navigation & Search" +description = "" +weight = 30 ++++ + +Docport allow you to easily customize header, left & righ sidebars and footer. + +Some placeHolders and entry points location exists to embed custom content, without modification of the theme. + +{{%notice success%}} +These custom contents could be full HTML or Markdown files. +{{%/notice %}} + +{{%children style="h2" %}} + + diff --git a/exampleSite/content/content-and-customization/02-navigation-search/menu/_index.md b/exampleSite/content/content-and-customization/02-navigation-search/menu/_index.md new file mode 100644 index 0000000..cc2eda9 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/menu/_index.md @@ -0,0 +1,85 @@ ++++ +title = "Menu" +description = "" +weight = 20 + ++++ + + +Docport's Menu displays your content structure on left. +* the 2 dashed rectangles are 2 position where you can inject custom content, see bellow +* menu entries are controled by each content page frontmatter options + + + +## Menu entry labels +Each of your content/ folder sections are an entry, their `_index.md` file is used to get information about how to render each one, thanks to frontmatter. + +{{%notice warning%}} +Reminder : [subpages]({{%relref "content-and-customization/00-adding-content#subpages"%}}) are not rendered in this menu +{{%/notice%}} + +Bellow are all frontmatters options used to render a menu entry.\ +Example from the current "Getting start" section. + +```toml ++++ +# Menu label +title = "Getting started" + +# Hide this page from menu +hidden = false + +# Prefix menu label with a text, an html... +pre = "" + +# Suffix menu label with a text, an html... +post = "👋" + +# Display this before the menu entry +head = "<hr/>" + +# Keep this menu opened by default +alwaysopen = true + ++++ +``` + + + +## Add content before menu entries +(red dashed rectangle in the screenshot) + +Create a `_index.md` page in `_layout/_sidepage-before` folder. + +```bash + content/ + └── _layout + └── sidepage-before + ├── _index.md + └── _index.fr.md +``` + +{{%alert info%}}**Remember :** You can put a full HTML content in your .md files{{%/alert%}} + +{{%alert info%}}**Tip :** You can remove search box if you need to [see more here]({{%relref "search"%}}) + +{{%/alert%}} + +## Add content after menu entries +(blue dashed rectangle in the screenshot) + +Create a `_index.md` page in `_layout/_sidepage-after` folder. + +```bash + content/ + └── _layout + └── sidepage-after + ├── _index.md + └── _index.fr.md +``` + + +## Hide site menu +Set `hide_nav=true` in your page's frontmatter, see [an example here]({{%relref "examples/page without sidebar and toc"%}}) + diff --git a/exampleSite/content/content-and-customization/02-navigation-search/menu/screenshot.png b/exampleSite/content/content-and-customization/02-navigation-search/menu/screenshot.png Binary files differnew file mode 100644 index 0000000..71cfa83 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/menu/screenshot.png diff --git a/exampleSite/content/content-and-customization/02-navigation-search/screenshot.png b/exampleSite/content/content-and-customization/02-navigation-search/screenshot.png Binary files differnew file mode 100644 index 0000000..91bd297 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/screenshot.png diff --git a/exampleSite/content/content-and-customization/02-navigation-search/search/_index.md b/exampleSite/content/content-and-customization/02-navigation-search/search/_index.md new file mode 100644 index 0000000..0ac33e0 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/search/_index.md @@ -0,0 +1,24 @@ +--- +title: Search Engine +description: search engine +weight: 400 +date: 2020-08-20T16:31:33.621Z +post: "" +--- + + +Docport theme uses the last improvement available in hugo version 20+ to generate a json index file ready to be consumed by lunr.js javascript search engine. + +hugo generate lunrjs index.json at the root of `public` folder if the site only has one language or within each language subfolder. + +{{%notice warning%}}When you build the site with `hugo server`, hugo generates it internally and of course it don't show up in the filesystem{{%/notice%}} + + +## Disable search +You can disable this functionality with `disableSearch` param in you site `config.toml` + + +``` toml + [params] + disableSearch = true +``` diff --git a/exampleSite/content/content-and-customization/02-navigation-search/thefooter/_index.md b/exampleSite/content/content-and-customization/02-navigation-search/thefooter/_index.md new file mode 100644 index 0000000..399c203 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/thefooter/_index.md @@ -0,0 +1,31 @@ ++++ +title = "Footer" +description = "" +weight = 100 + ++++ + +Docport's Footer displays what you want ! + + + +## Set your footer + +Create a `_layout/footer/_index.md` page in content root folder. +Its content is what you get in the footer + +```bash + content/ + └── _layout + └── footer + ├── _index.md + └── _index.fr.md +``` + +This allow you to define a localized footer content. + +{{%alert info%}}**Tip :** You can put a full HTML content in your `_index.md` file{{%/alert%}} + +## Hide site footer +Set `hide_footer=true` in your page's frontmatter, see [an example here]({{%relref "examples/page without footer"%}}) + diff --git a/exampleSite/content/content-and-customization/02-navigation-search/thefooter/screenshot.png b/exampleSite/content/content-and-customization/02-navigation-search/thefooter/screenshot.png Binary files differnew file mode 100644 index 0000000..f503504 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/thefooter/screenshot.png diff --git a/exampleSite/content/content-and-customization/02-navigation-search/theheader/_index.md b/exampleSite/content/content-and-customization/02-navigation-search/theheader/_index.md new file mode 100644 index 0000000..e13929f --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/theheader/_index.md @@ -0,0 +1,61 @@ ++++ +title = "Header" +description = "" +weight = 10 + ++++ + +Docport's Header displays Site Title and Site shortcuts. + + + +## Site Title +As defined in site `config.toml` + + +## Site shortcuts (Top level menu) +If you want to add a link to a page or an external site to this menu, add it in `config.toml`, specifying the weight to order them. + +```toml + [[menu.shortcuts]] + name = "Github" + identifier = "ds" + url = "https://github.com/vjeantet/hugo-theme-docport" + weight = 10 + + [[menu.shortcuts]] + name = "Download" + url = "https://github.com/vjeantet/hugo-theme-docport/archive/master.zip" + weight = 11 + + [[menu.shortcuts]] + name = "Hugo Documentation" + identifier = "hugodoc" + url = "https://gohugo.io/" + weight = 20 + + [[menu.shortcuts]] + name = "Credits" + url = "/docport-theme/credits/" + weight = 30 +``` + +[{{%icon star %}} Read more about hugo and menu here](https://gohugo.io/extras/menus/) + +## Overide header content + +Create a `_layout/header/_index.md` page in content root folder. +Its content is what you get in the header (site shortscurs remains) + +```bash + content/ + └── _layout + └── header + ├── _index.md + └── _index.fr.md +``` + +This allow you to define a localized header content. + +## Hide site header +Set `hide_header=true` in your page's frontmatter, see [an example here]({{%relref "examples/page without header"%}})
\ No newline at end of file diff --git a/exampleSite/content/content-and-customization/02-navigation-search/theheader/screenshot.png b/exampleSite/content/content-and-customization/02-navigation-search/theheader/screenshot.png Binary files differnew file mode 100644 index 0000000..ec53b38 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/theheader/screenshot.png diff --git a/exampleSite/content/content-and-customization/02-navigation-search/toc/_index.md b/exampleSite/content/content-and-customization/02-navigation-search/toc/_index.md new file mode 100644 index 0000000..9f479b9 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/toc/_index.md @@ -0,0 +1,47 @@ ++++ +title = "Content right bar" +description = "" +weight = 50 + ++++ + +With each page, a sidebar is displayed on the right side, with the current table of content. +* the 2 dashed rectangles are 2 position where you can inject custom content, see bellow + + + +## Add content before the Table of content +(red dashed rectangle in the screenshot) + +Create a `_index.md` page in `_layout/_sidepage-before` folder. + +```bash + content/ + └── _layout + └── article-sidepage-before + ├── _index.md + └── _index.fr.md +``` + +## Add content after the Table of content +(blue dashed rectangle in the screenshot) + +Create a `_index.md` page in `_layout/_sidepage-after` folder. + +```bash + content/ + └── _layout + └── article-sidebar-after + ├── _index.md + └── _index.fr.md +``` + +{{%alert info%}}**Remember :** You can put a full HTML content in your .md files{{%/alert%}} + +{{%alert info%}}**Tip :** You can remove search box if you need to [see more here]({{%relref "search"%}}) + +{{%/alert%}} + + +## Hide right sidebar +Set `hide_toc=true` in your page's frontmatter, see [an example here]({{%relref "examples/page without toc"%}}) diff --git a/exampleSite/content/content-and-customization/02-navigation-search/toc/screenshot.png b/exampleSite/content/content-and-customization/02-navigation-search/toc/screenshot.png Binary files differnew file mode 100644 index 0000000..c259550 --- /dev/null +++ b/exampleSite/content/content-and-customization/02-navigation-search/toc/screenshot.png diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/_index.md b/exampleSite/content/content-and-customization/03-look-and-feel/_index.md new file mode 100644 index 0000000..92bb1f9 --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/_index.md @@ -0,0 +1,14 @@ ++++ +title = "Look and feel" +Weight=40 ++++ + +You can change the style and behavior of the theme without touching its source code. +* Change base colors +* Disable features +* Overide existing css or js with your own files +* Inject your own html, css or js into the page, see [navigation & Search]({{%relref "02-navigation-search"%}}) + + + +{{%children style="h2" %}} diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/_index.md b/exampleSite/content/content-and-customization/03-look-and-feel/colors/_index.md new file mode 100644 index 0000000..171fd8b --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/_index.md @@ -0,0 +1,46 @@ ++++ +title="Colors" +subpage=true + ++++ + +By default, a site using docPort has the theme’s default color.\ +However, if you want your own color scheme (and you probably will!) you can very easily override the theme defaults with your own project-specific values - Hugo will look in your project files first when looking for information to build your site. + +This theme use 2 colors, named as "main" and "second" color and compute other colors from them. + +You can set theses colors by editing the **site config.toml** file. + +## Main color +This color is mainly used on left menu, a darker version is used for header background and content text. + +{{% notice primary %}}When omited, a random value is computed on build{{%/notice%}} + +```toml + [params] + color_main = "#B0B0B0" +``` + +## 2nd color +This color is mainly used for links.\ +When omited, this color is computed from main color with a saturated calculation. + +```toml + [params] + color_second = "red" +``` + +## Random colors + +Comment theses two params in your config.toml, you will have random colors on each build... :) + + + +Examples of random colors + + + + + + + diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/color001.png b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color001.png Binary files differnew file mode 100644 index 0000000..636f5df --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color001.png diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/color002.png b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color002.png Binary files differnew file mode 100644 index 0000000..2195929 --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color002.png diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/color003.png b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color003.png Binary files differnew file mode 100644 index 0000000..b97babf --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color003.png diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/color004.png b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color004.png Binary files differnew file mode 100644 index 0000000..464ed4a --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color004.png diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/color005.png b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color005.png Binary files differnew file mode 100644 index 0000000..755e7d6 --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color005.png diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/color006.png b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color006.png Binary files differnew file mode 100644 index 0000000..3b363ec --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color006.png diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/colors/rainbow.gif b/exampleSite/content/content-and-customization/03-look-and-feel/colors/rainbow.gif Binary files differnew file mode 100644 index 0000000..27bf1d6 --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/colors/rainbow.gif diff --git a/exampleSite/content/content-organisation/customize-style/_index.md b/exampleSite/content/content-and-customization/03-look-and-feel/css-js/_index.md index 4979fb4..52d4aed 100644 --- a/exampleSite/content/content-organisation/customize-style/_index.md +++ b/exampleSite/content/content-and-customization/03-look-and-feel/css-js/_index.md @@ -1,17 +1,8 @@ +++ -title = "Customize look and feel" -Weight=3 -+++ - -You can change the style and behavior of the theme without touching its source code. +title="CSS & JS" +subpage=true -* inject your own html, css or js into the page -* overide existing css or js with your own files - -{{%notice warning %}} -No needs to copy the entire theme to customize some parts -Bellow are solutions to avoid copying the entire theme into your own codebase. -{{%/notice%}} ++++ ## Add custom CSS and JS into the \<head\> part of each page : @@ -50,7 +41,7 @@ now feel free to add the JS, CSS code you want :) ## Add custom HTML before and after key elements of this theme -* @see [site placeholders]({{%relref "content-organisation/placeholders/_index.md"%}}) +* @see [site placeholders]({{%relref "02-navigation-search"%}}) ## Overide existing CSS or JS diff --git a/exampleSite/content/content-organisation/customize-style/disable/_index.md b/exampleSite/content/content-and-customization/03-look-and-feel/disable/_index.md index 07bd1a3..b35401f 100644 --- a/exampleSite/content/content-organisation/customize-style/disable/_index.md +++ b/exampleSite/content/content-and-customization/03-look-and-feel/disable/_index.md @@ -7,13 +7,10 @@ You can disable feature in docport by changing some params in `config.toml` ## Hide Next Page Chevrons -```toml - [params] - disableNavChevron = true -``` -## Hide Search box in side menu + + ```toml [params] - disableSearch = true + disableNavChevron = true ``` diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/disable/chevrons.png b/exampleSite/content/content-and-customization/03-look-and-feel/disable/chevrons.png Binary files differnew file mode 100644 index 0000000..2d8a08b --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/disable/chevrons.png diff --git a/exampleSite/content/content-and-customization/04-shortcodes/_index.md b/exampleSite/content/content-and-customization/04-shortcodes/_index.md new file mode 100644 index 0000000..bce46b5 --- /dev/null +++ b/exampleSite/content/content-and-customization/04-shortcodes/_index.md @@ -0,0 +1,10 @@ ++++ +title = "Shortcodes" +description = "Use DocPort Hugo shortcodes to quickly build site pages." +weight = 50 +redirect = "shortcodes" ++++ + + + + diff --git a/exampleSite/content/content-and-customization/_index.md b/exampleSite/content/content-and-customization/_index.md new file mode 100644 index 0000000..1ec5391 --- /dev/null +++ b/exampleSite/content/content-and-customization/_index.md @@ -0,0 +1,7 @@ ++++ +title = "Content and Customization" +description = "" +weight = 30 ++++ + +{{%children style="h2" description="true" %}} diff --git a/exampleSite/content/content-organisation/_index.md b/exampleSite/content/content-organisation/_index.md deleted file mode 100644 index 368f4ed..0000000 --- a/exampleSite/content/content-organisation/_index.md +++ /dev/null @@ -1,98 +0,0 @@ -+++ -title = "Content Organisation" -description = "" -weight = 20 -+++ - -With **Hugo**, pages are the core of your site. Organize your site like any other Hugo project. **Magic occurs with the nested sections implemention done since v0.22 of hugo (congrats @bep)**. - -With docport, **Each content page composes the menu**, they shape the structure of your website. - -To link pages to each other, place them in a folders hierarchy - -```text - content - ├── _index.md <-- homepage - └── folder-one/ - ├── _index.md <-- used as homepage if content/_index.md does not exists - └── folder-one-two/ <-- section displayed in left menu - ├── _index.md <-- section's page - ├── folder-one-two-three-A/ - │ ├── _index.md - └── folder-one-two-three-B/ <- section displayed in left menu - ├── _index.md <-- section's page - ├── page3BA.md <-- "subpages" - └── page3BB.md <-- "subpages" - -``` - - -{{%alert info %}} -**_index.md** is required in each folder (section) : this is the "page" which define section title, content, etc.... - -**other.md** files are considered as "subpages" -{{%/alert%}} - -## Subpages ⊷ - -Each other **.md** found in a section folder will be considered "subpages", for example, in the `content-organisation` folder there is 1 _index.md (the one your are currently reading) and 1 more files named "extramenu.md", they appear just under this page's title, look upper. - - - - -## Add header to a menu entry - -in the page frontmatter, add a `head` param to insert any HTML code before the menu entry: - -example to display a "Hello" - -```toml - +++ - title = "Github repo" - head ="Hello" - +++ -``` - -## Order sibling menu/page entries - -in your frontmatter add `weight` param with a number to order. - -```toml - +++ - title="My page" - weight = 4 - +++ -``` -{{%notice tip%}} you can order pages by title by adding `ordersectionsby = "title"` in your config.toml {{%/notice%}} - -## Hide a menu entry - -in your frontmatter add `hidden=true` param. -```toml - +++ - title="My page" - hidden = true - +++ -``` - -## Keep menu entry opened by default - -One or more menuentries can be displayed unfolded by default. (like the "Getting start" menu entry in this website) - -in your frontmatter add `alwaysopen=true` param. -example : - -```toml - title = "Getting start" - description = "" - weight = 1 - alwaysopen = true -``` - - -## Homepage - -Find out how to [customize homepage]({{%relref "create-page/set-your-homepage/_index.md"%}}) - - - diff --git a/exampleSite/content/content-organisation/customize-style/colors/_index.md b/exampleSite/content/content-organisation/customize-style/colors/_index.md deleted file mode 100644 index 7e348e7..0000000 --- a/exampleSite/content/content-organisation/customize-style/colors/_index.md +++ /dev/null @@ -1,31 +0,0 @@ -+++ -title="Colors" -subpage=true - -+++ - -This theme use 1 main color to compute other colors and colorize all elements. -You can choose this main color by editing the `config.toml` file. - -## Main color - -This color is mainly used for menu. - -{{% notice primary %}}When omited, a random value is computed on each build {{%/notice%}} -```toml - [params] - color_main = "#B0B0B0" -``` - -## 2nd color (optional) -{{% notice primary %}}When omited, this color is computed from main color with a saturated version{{%/notice %}} - -This color is mainly used for links. - -```toml - [params] - color_second = "red" -``` - -## Random colors -{{%alert success%}}**Random colors** : comment theses two params in your config.toml, you will have random colors on each build... {{%/alert%}}
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/customize-style/disable/test.md b/exampleSite/content/content-organisation/customize-style/disable/test.md deleted file mode 100644 index 8c22591..0000000 --- a/exampleSite/content/content-organisation/customize-style/disable/test.md +++ /dev/null @@ -1,18 +0,0 @@ -+++ -title = "test A" -+++ - -You can disable feature in docport by changing some params in `config.toml` - - -## hide Next / Prev Chevrons -```toml - [params] - disableNavChevron = true -``` - -## hide Search box in side menu -```toml - [params] - disableSearch = true -``` diff --git a/exampleSite/content/content-organisation/customize-style/disable/test2.md b/exampleSite/content/content-organisation/customize-style/disable/test2.md deleted file mode 100644 index 0e220f9..0000000 --- a/exampleSite/content/content-organisation/customize-style/disable/test2.md +++ /dev/null @@ -1,18 +0,0 @@ -+++ -title = "test B" -+++ - -You can disable feature in docport by changing some params in `config.toml` - - -## hide Next / Prev Chevrons -```toml - [params] - disableNavChevron = true -``` - -## hide Search box in side menu -```toml - [params] - disableSearch = true -``` diff --git a/exampleSite/content/content-organisation/customize-style/theme-variants/_index.md b/exampleSite/content/content-organisation/customize-style/theme-variants/_index.md deleted file mode 100644 index b18976a..0000000 --- a/exampleSite/content/content-organisation/customize-style/theme-variants/_index.md +++ /dev/null @@ -1,36 +0,0 @@ -+++ -draft = true -title = "Theme variants" -description = "change theme style/colors" -+++ - -In site configuration file, you can set a variant name of this theme to load a specific css, with different color specifications. - -add a param `themeVariant = "VARIANT_NAME"` in the `[params]` part of config.toml file. - -{{%info%}}Available variants change only colors at this moment{{%/info%}} - - -## Variant "gray" -``` -[params] -themeVariant = "gray" -``` - - - -## Variant "gold" -``` -[params] -themeVariant = "gold" -``` - - - -## Variant "green" -``` -[params] -themeVariant = "green"` -``` - -
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/customize-style/themestyle/_index.md b/exampleSite/content/content-organisation/customize-style/themestyle/_index.md deleted file mode 100644 index 77013d9..0000000 --- a/exampleSite/content/content-organisation/customize-style/themestyle/_index.md +++ /dev/null @@ -1,26 +0,0 @@ -+++ -draft = true -title = "Theme styles" -description = "change theme style" -+++ - -In site configuration file, you can set a subtheme name of this theme to load a specific css. - -add a param `themeStyle = "STYLE_NAME"` in the `[params]` part of config.toml file. - - -## Style "original" -``` -[params] -themeStyle = "original" -``` - - - -## Style "flex" (work in progress) -``` -[params] -themeStyle = "flex" -``` - -
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/extramenu/_index.md b/exampleSite/content/content-organisation/extramenu/_index.md deleted file mode 100644 index 7d583cc..0000000 --- a/exampleSite/content/content-organisation/extramenu/_index.md +++ /dev/null @@ -1,31 +0,0 @@ -+++ -title = "Extra menu entries" -date = "2017-04-29T18:36:24+02:00" -Weight=2 -+++ - -You can define additional menu entries in the top navigation menu. - -Edit the website configuration `config.toml` and add a `[[menu.shortcuts]]` entry for each link your want to add. - -Example from the current website. - -```toml - [[menu.shortcuts]] - name = "<i class='material-icons'>cloud_download</i> Download" - url = "https://github.com/vjeantet/hugo-theme-docport/archive/master.zip" - weight = 11 - - [[menu.shortcuts]] - name = "Hugo Documentation" - identifier = "hugodoc" - url = "https://gohugo.io/" - weight = 20 - - [[menu.shortcuts]] - name = "Credits" - url = "/credits" - weight = 30 -`` - -[{{%icon circle-arrow-right%}} Read more about hugo and menu here](https://gohugo.io/extras/menus/)
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/placeholders/_index.md b/exampleSite/content/content-organisation/placeholders/_index.md deleted file mode 100644 index e76cbb5..0000000 --- a/exampleSite/content/content-organisation/placeholders/_index.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Site placeholders" -description = "" -weight = 20 -+++ - -PlaceHolders are location in theme where you can embed custom content, without modification of the theme. - -These custom content could be full HTML or Markdown files - -## Placeholder locations -* [Header]({{%relref "header.md"%}}) -* [Left menu]({{%relref "menu.md"%}}) (before and after menu tree) -* [Right menu]({{%relref "toc.md"%}}) (before and after table of content) -* [Footer]({{%relref "thefooter.md"%}})
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/placeholders/header/_index.md b/exampleSite/content/content-organisation/placeholders/header/_index.md deleted file mode 100644 index 5e1c2ce..0000000 --- a/exampleSite/content/content-organisation/placeholders/header/_index.md +++ /dev/null @@ -1,19 +0,0 @@ -+++ -title = "Header" -description = "" -weight = 10 -subpage = true -+++ - - -Create a `_header.md` page in content root folder. Its content is what you get in the header. - -```bash - content/ - ├── _header.md - └── _header.fr.md -``` - -{{%alert info%}}**Tip :** look at -* [ extra static menu]({{%relref "content-organisation/extramenu/_index.md"%}}) if you want to add (or remove) header links -{{%/alert%}}
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/placeholders/menu/_index.md b/exampleSite/content/content-organisation/placeholders/menu/_index.md deleted file mode 100644 index fd6bb63..0000000 --- a/exampleSite/content/content-organisation/placeholders/menu/_index.md +++ /dev/null @@ -1,33 +0,0 @@ -+++ -title = "Menu" -description = "" -weight = 20 -subpage = true -+++ - - -## Before menu entries in left nav bar -Create a `_sidepage-before.md` page in content root folder. - -```bash - content/ - ├── _sidepage-before.md - └── _sidepage-before.fr.md -``` - - -## After menu entries in left nav bar -Create a `_sidepage-after.md` page in content root folder. - -```bash - content/ - └── _sidepage-after.md -``` - - - -{{%alert info%}}**Tip :** You can put a full HTML content in your .md files{{%/alert%}} - -{{%alert info%}}**Tip :** You can [ hide search box ]({{%relref "content-organisation/customize-style/disable/_index.md"%}}) if you want to remove the search box from header - -{{%/alert%}}
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/placeholders/thefooter/_index.md b/exampleSite/content/content-organisation/placeholders/thefooter/_index.md deleted file mode 100644 index 49f828a..0000000 --- a/exampleSite/content/content-organisation/placeholders/thefooter/_index.md +++ /dev/null @@ -1,17 +0,0 @@ -+++ -title = "Footer" -description = "" -weight = 100 -subpage = true -+++ - - -Create a `_footer.md` page in content root folder. Its content is what you get in the footer. - -```bash - content/ - ├── _footer.md - └── _footer.fr.md -``` - -{{%alert info%}}**Tip :** You can put a full HTML content in your .md file{{%/alert%}}
\ No newline at end of file diff --git a/exampleSite/content/content-organisation/placeholders/toc/_index.md b/exampleSite/content/content-organisation/placeholders/toc/_index.md deleted file mode 100644 index 6c35e95..0000000 --- a/exampleSite/content/content-organisation/placeholders/toc/_index.md +++ /dev/null @@ -1,28 +0,0 @@ -+++ -title = "Table of content" -description = "" -weight = 50 -subpage = true -+++ - - -## Before Table of contents in right bar -Create a `_article-sidepage-before.md` page in content root folder. - -```bash - content/ - ├── _article-sidepage-before.md - └── _article-sidepage-before.fr.md -``` - - -## After Table of contents in right bar -Create a `_article-sidepage-after.md` page in content root folder. - -```bash - content/ - └── _article-sidepage-after.md -``` - - -{{%alert info%}}**Tip :** You can put a full HTML content in your .md files{{%/alert%}}
\ No newline at end of file diff --git a/exampleSite/content/create-page/_index.md b/exampleSite/content/create-page/_index.md deleted file mode 100644 index 9a2ff6f..0000000 --- a/exampleSite/content/create-page/_index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -post: 👋 -lastmodifierdisplayname: Valere JEANTET -title: Create Page -description: Create page -date: 2017-04-24T18:36:24+02:00 -layout: "" -hidden: false -head: "" -creatordisplayname: Valere JEANTET -pre: "" -lastmodifieremail: valere.jeantet@gmail.com -creatoremail: valere.jeantet@gmail.com -weight: 10 -tags: - - tag1 - - tag2 ---- - - -Hugo-theme-docport uses two types of pages. _Default_ and [_Slide_]({{%relref "create-page/page-slide/_index.md"%}}). - -## Page params -Each page may define a Front Matter in yaml, toml or json. - -Hugo-theme-docport uses the following parameters on top of the existing ones : - -```toml -+++ -title="Create Page" - -subpage = false # When a page is a subpage, it will be displayed bellow the parent page title, and not in the left menu - - -# Ajust layout for your page -hide_header=false # set true to hide site header -hide_nav=false # set true to hide the left navigation menu -hide_breadcrumb=false # set true to hide the breadcrumb -hide_toc=false # set true to hide the right menu (table of contents) -hide_footer=false #set true to hide the website footer -+++ -``` - - - -## Ordering - -Hugo provides a flexible way to handle order for your pages. - -The simplest way is to use `weight` parameter in the front matter of your page. - -```toml -+++ -weight = 10 -+++ -``` - -[{{%icon play_circle_filled%}}Read more on content organization]({{%relref "content-organisation/_index.md"%}}) - - - - - diff --git a/exampleSite/content/create-page/control-page-menu/_index.md b/exampleSite/content/create-page/control-page-menu/_index.md deleted file mode 100644 index e584e8f..0000000 --- a/exampleSite/content/create-page/control-page-menu/_index.md +++ /dev/null @@ -1,37 +0,0 @@ -+++ -title="Navigation entries" -pre = "👻 " -post = " 👋" -subpage = true -hidden = false -weight = 300 -+++ - -Each page is displayed on navigation bars -* _index.md files are displayed on the left menu -* other files are displayed as subpages (like this one) bellow the section title. - - -You can control how they are displayed thanks to page FrontMatter. - -Hugo-theme-docport uses the following parameters to acheive this : - -```toml -+++ -# Hide this page from navigation -hidden = false - - -# Display before and after in navigations menus surrounding page's title -pre = "👻" -post = "👋" - -# LEFT MENU ONLY (Sections) -# as an exemple, on the Getting started Page a head="<hr/>" is set -head = "<hr/>" - -# Menu opened by default (like the Getting started menu entry) -alwaysopen = false - -+++ -```
\ No newline at end of file diff --git a/exampleSite/content/create-page/page-images/_index.md b/exampleSite/content/create-page/page-images/_index.md deleted file mode 100644 index 6ea26c1..0000000 --- a/exampleSite/content/create-page/page-images/_index.md +++ /dev/null @@ -1,31 +0,0 @@ -+++ -title = "With images" -date = "2017-04-24T18:36:24+02:00" -weight = 10 -hidden = false -subpage = true -+++ - -Images have a similar syntax to links but include a preceding exclamation point. - -  - - - -## Resizing image - -Add HTTP parameters `width` and/or `height` to the link image to resize the image. Values are CSS values (default is `auto`). - - -  - - - - -## Add CSS classes - -Add a HTTP `classes` parameter to the link image to add CSS classes. `shadow` and `border` are available but you could define other ones. - -  - - diff --git a/exampleSite/content/create-page/set-your-homepage/_index.md b/exampleSite/content/create-page/set-your-homepage/_index.md deleted file mode 100644 index 88486ad..0000000 --- a/exampleSite/content/create-page/set-your-homepage/_index.md +++ /dev/null @@ -1,27 +0,0 @@ -+++ -title="Create homepage" -+++ - - - -{{% alert theme="success" %}}By default, this theme use the first section (folder) available in your content folder as a homepage.{{%/alert%}} - -## Create a dedicated homepage -To tell Hugo-theme-docport to consider a page as homepage's content, just create a content file named `_index.md` in `content` root folder. -* use `hide_header`,`hide_nav`,`hide_breadcrumb`,`hide_toc`,`hide_footer` params in frontmatter to control what to show/hide for this page - -## Use plain HTML for your homepage -set a `layout=raw` param in frontmatter, your content will render without any navigation, menu, header, footer. - - -Example -```toml -+++ -title="Homepage" -layout="raw" -+++ -<div class="myHome"> - Hello -</div> -``` - diff --git a/exampleSite/content/docport-theme/credits/_index.md b/exampleSite/content/docport-theme/credits/_index.md index 1fcbc1e..8a64a85 100644 --- a/exampleSite/content/docport-theme/credits/_index.md +++ b/exampleSite/content/docport-theme/credits/_index.md @@ -61,7 +61,7 @@ hide_toc=true <div style="margin:7px"> <img src="https://avatars2.githubusercontent.com/u/3520706?v=3" class="inline" width="32" height="32" style="height: 32px;height: 32px; vertical-align:middle; "> <span> - <a href="https://github.com/bep">@matcornic</a> + <a href="https://github.com/matcornic">@matcornic</a> <label>inspiration and support</label> </span> </div> diff --git a/exampleSite/content/examples/_index.md b/exampleSite/content/examples/_index.md new file mode 100644 index 0000000..e2fc9c9 --- /dev/null +++ b/exampleSite/content/examples/_index.md @@ -0,0 +1,9 @@ +--- +title: Examples +weight: 50 + +--- + +some examples + +{{% children description="true" %}}
\ No newline at end of file diff --git a/exampleSite/content/examples/page with raw content/_index.md b/exampleSite/content/examples/page with raw content/_index.md new file mode 100644 index 0000000..56cdb32 --- /dev/null +++ b/exampleSite/content/examples/page with raw content/_index.md @@ -0,0 +1,21 @@ +--- +title: A page with raw content +layout: raw +description: Nothing but your content ! usefull for special pages +weight: 99 +--- + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud <b>exercitation</b> ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
\ No newline at end of file diff --git a/exampleSite/content/examples/page without footer/_index.md b/exampleSite/content/examples/page without footer/_index.md new file mode 100644 index 0000000..7b5c3de --- /dev/null +++ b/exampleSite/content/examples/page without footer/_index.md @@ -0,0 +1,20 @@ +--- +title: A page without footer +weight: 20 +hide_footer: true +--- + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
\ No newline at end of file diff --git a/exampleSite/content/examples/page without header/_index.md b/exampleSite/content/examples/page without header/_index.md new file mode 100644 index 0000000..99c19f2 --- /dev/null +++ b/exampleSite/content/examples/page without header/_index.md @@ -0,0 +1,21 @@ +--- +title: A page without header +weight: 20 +hide_header: true + +--- + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
\ No newline at end of file diff --git a/exampleSite/content/examples/page without sidebar and toc/_index.md b/exampleSite/content/examples/page without sidebar and toc/_index.md new file mode 100644 index 0000000..b91c9d0 --- /dev/null +++ b/exampleSite/content/examples/page without sidebar and toc/_index.md @@ -0,0 +1,21 @@ +--- +title: A page without sidebar and toc +weight: 20 +hide_toc: true +hide_nav: true +--- + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
\ No newline at end of file diff --git a/exampleSite/content/examples/page without toc/_index.md b/exampleSite/content/examples/page without toc/_index.md new file mode 100644 index 0000000..84a91b2 --- /dev/null +++ b/exampleSite/content/examples/page without toc/_index.md @@ -0,0 +1,20 @@ +--- +title: A page without table of contents +weight: 20 +hide_toc: true +--- + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + + +Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod +tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, +quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo +consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse +cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non +proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
\ No newline at end of file diff --git a/exampleSite/content/getting-start/_index.md b/exampleSite/content/getting-start/_index.md index 3627c26..e4cc847 100644 --- a/exampleSite/content/getting-start/_index.md +++ b/exampleSite/content/getting-start/_index.md @@ -1,10 +1,12 @@ --- +post: " 👋" title: Getting started description: Getting started date: 2020-08-20T16:42:11.812Z weight: 2 head: <hr/> alwaysopen: true + --- ## Requirements diff --git a/exampleSite/content/getting-start/configuration/_index.md b/exampleSite/content/getting-start/configuration/_index.md index 6eaf97e..0e7588b 100644 --- a/exampleSite/content/getting-start/configuration/_index.md +++ b/exampleSite/content/getting-start/configuration/_index.md @@ -4,53 +4,22 @@ description = "" weight = 2 +++ -When building the website, you can set a theme by using `--theme` option. We suggest you to edit your configuration file and set the theme by default. Example with `config.toml` format. -<!--more--> -Import sample config from sample site to Hugo root: +There are a few configuration options that you can add to your `config.toml` file. -``` -$ cp themes/docport/exampleSite/config.toml . -``` - -Change following `config.toml` line as needed, depending on method above: -``` -theme = "<hugo-theme-docport-dir-name>" -``` -Comment out following line, so default `themes/` will be used: - -``` -# themesdir = "../.." -``` - - -{{%excerpt%}} -## Activate search - -If not already present, add the follow lines to the `config.toml` file. - -```toml -[outputs] -home = [ "HTML", "RSS", "JSON"] -``` -{{% /excerpt%}} - - -LUNRJS search index file will be generated on content changes. - -#### (Bonus) -Create empty file `.gitkeep` inside `public/` and add following to `.gitignore`. This way it will keep repo smaller and won't bring build result files and errors to remote checkout places: -```bash -/public/* -!/public/.gitkeep -``` +{{%notice tip%}} +**Tip** +\ +Use the sample [config.toml](https://github.com/vjeantet/hugo-theme-docport/blob/master/exampleSite/config-template.toml) from docPort example site as a blueprint for your Hugo project: +{{%/notice%}} -### Preview site +## Use the docport theme +When building the website, you can set a theme by passing the `--theme` argument on command line. +We suggest you to edit your config.toml configuration file and set the theme by default. ``` -$ hugo server +theme = "docport" ``` -to browse site on http://localhost:1313 -## Your website's content +## Create content and customize the theme -Find out how to [create]({{%relref "create-page/_index.md"%}}) and [organize your content]({{%relref "content-organisation/_index.md"%}}) quickly and intuitively. +Find out how to [create]({{%relref "create-page/_index.md"%}}) and [customize the theme to fit your needs]({{%relref "customization/_index.md"%}}) . diff --git a/exampleSite/content/getting-start/installation/As-git-clone/_index.md b/exampleSite/content/getting-start/installation/As-git-clone/_index.md new file mode 100644 index 0000000..ddcec2d --- /dev/null +++ b/exampleSite/content/getting-start/installation/As-git-clone/_index.md @@ -0,0 +1,20 @@ ++++ +title = "with git clone" +description = "" +subpage = true +weight = 1 ++++ + +## Install DocPort with a git clone + +Navigate to your hugo root folder in your Hugo site and use perform one of following scenarios. + +This method results that files are checked out locally, but won't be visible from parent git repo. Probably you will build site locally with `hugo` command and use result from `public/` on your own. + +``` +$ git clone https://github.com/vjeantet/hugo-theme-docport.git themes/docport +``` + +## Configuration + +[Follow instructions here]({{%relref "getting-start/configuration/_index.md"%}}) diff --git a/exampleSite/content/getting-start/installation/_index.md b/exampleSite/content/getting-start/installation/_index.md index b3b1212..33cc35b 100644 --- a/exampleSite/content/getting-start/installation/_index.md +++ b/exampleSite/content/getting-start/installation/_index.md @@ -2,6 +2,7 @@ title = "Installation" description = "" weight = 1 + +++ {{% alert theme="warning" %}}HUGO **v0.50** minimum required to use this theme (prefer extended version if you want to modify this theme source{{%/alert%}} @@ -11,17 +12,11 @@ weight = 1 The following steps are here to help you initialize your new website. If you don’t know Hugo at all, we strongly suggest you to train by following this [great documentation for beginners](https://gohugo.io/overview/quickstart/). <!--more--> -## Installation - -We assume that all changes to Hugo content and customizations are going to be tracked by git (GitHub, Bitbucket etc.). Develop locally, build on remote system. -Before start real work: -1. Initialize Hugo -2. Install DocPort theme -3. Configure DocPort and Hugo +We assume that all changes to Hugo content and customizations are going to be tracked by git (GitHub, Bitbucket etc.). Develop locally, build on remote system. -### Prepare empty Hugo site +## Prepare empty Hugo site Create empty directory, which will be root of your Hugo project. Navigate there and let Hugo to create minimal required directory structure: ``` @@ -32,21 +27,17 @@ After that, initialize this as git directory where to track further changes $ git init ``` -### Install DocPort - -Next, there are at least three ways to install DocPort (first recommended): +## Install DocPort as git submodule -1. **As git submodule** -2. As git clone -3. As direct copy (from ZIP) - -Navigate to your themes folder in your Hugo site and use perform one of following scenarios. - -#### 1. Install DocPort as git submodule +{{%alert%}} +**Alernatives to submodules** +\ +There are other ways to install DocPort. If submodule is no-go, use [install as git clone]({{%ref "as-git-clone/_index.md"%}}) or [install from a zip archive]({{%ref "direct copy/_index.md"%}}) +{{%/alert%}} DocPort will be added like a dependency repo to original project. When using CI tools like Netlify, Jenkins etc., submodule method is required, or you will get `theme not found` issues. Same applies when building site on remote server trough SSH. -If submodule is no-go, use 3rd option. + On your root of Hugo execute: @@ -60,27 +51,8 @@ $ git submodule init $ git submodule update ``` -Now you are ready to add content and customize looks. Do not change any file inside themes directory. - -If you want to freeze changes to DocPort theme itself and use still submodules, fork private copy of DocPort and use that as submodule. When you are ready to update theme, just pull changes from origin to your private fork. - -#### 2. Install DocPort simply as git clone - -This method results that files are checked out locally, but won't be visible from parent git repo. Probably you will build site locally with `hugo` command and use result from `public/` on your own. - -``` -$ git clone https://github.com/vjeantet/hugo-theme-docport.git themes/docport -``` - - -#### 3. Install DocPort from ZIP - -All files from theme will be tracked inside parent repo, to update it, have to override files in theme. [{{%icon cloud_download%}} download zip](https://github.com/vjeantet/hugo-theme-docport/archive/master.zip) and extract inside `themes/`. - -``` -https://github.com/vjeantet/hugo-theme-docport/archive/master.zip -``` -Name of theme in next step will be `hugo-theme-docport-master`, can rename as you wish. +Now you are ready to add content and build your documentatyion. +{{%notice warning%}}Do not change any file inside themes directory.{{%/notice%}} ## Configuration diff --git a/exampleSite/content/getting-start/installation/direct copy/_index.md b/exampleSite/content/getting-start/installation/direct copy/_index.md new file mode 100644 index 0000000..e154958 --- /dev/null +++ b/exampleSite/content/getting-start/installation/direct copy/_index.md @@ -0,0 +1,24 @@ ++++ +title = "from zip archive" +description = "" +weight = 1 +subpage = true ++++ + +## Install DocPort from a zip archive + +Navigate to your hugo root folder in your Hugo site and use perform one of following scenarios. + +All files from theme will be tracked inside parent repo, to update it, have to override files in theme. [{{%icon cloud_download%}} download zip](https://github.com/vjeantet/hugo-theme-docport/archive/master.zip) and extract inside `themes/`. + +``` +https://github.com/vjeantet/hugo-theme-docport/archive/master.zip +``` + +Rename `hugo-theme-docport-master` folder to `docport`, to match configuration in next step. + +Name of theme in next step will be `docport`. + +## Configuration + +[Follow instructions here]({{%relref "getting-start/configuration/_index.md"%}}) diff --git a/exampleSite/content/search/_index.md b/exampleSite/content/search/_index.md deleted file mode 100644 index d7307e3..0000000 --- a/exampleSite/content/search/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: About the Search Engine -description: search engine -weight: 40 -date: 2020-08-20T16:31:33.621Z -post: "<i class='material-icons' >star_border</i> " ---- -{{%excerpt-include filename="getting-start/configuration/_index.md" /%}} - -Docport theme uses the last improvement available in hugo version 20+ to generate a json index file ready to be consumed by lunr.js javascript search engine. - -{{%note%}}hugo generate lunrjs index.json at the root of `public` folder if the site only has one language or within each language subfolder. <br/>When you build the site with `hugo server`, hugo generates it internally and of course it don't show up in the filesystem{{%/note%}} - - - diff --git a/exampleSite/content/shortcodes/alert/_index.md b/exampleSite/content/shortcodes/alert/_index.md index d69e3dd..91025ee 100644 --- a/exampleSite/content/shortcodes/alert/_index.md +++ b/exampleSite/content/shortcodes/alert/_index.md @@ -19,11 +19,12 @@ The `alert` shortcode allow you to highlight information in your page. They crea ## Basic examples +``` {{%/* alert theme="info" */%}}**this** is a text{{%/* /alert */%}} {{%/* alert theme="success" */%}}**Yeahhh !** is a text{{%/* /alert */%}} {{%/* alert theme="warning" */%}}**Be carefull** is a text{{%/* /alert */%}} {{%/* alert theme="danger" */%}}**Beware !** is a text{{%/* /alert */%}} - +``` {{% alert theme="info"%}}**this** is an info{{% /alert %}} {{% alert theme="success" %}}**Yeahhh !** is an success{{% /alert %}} {{% alert theme="warning" %}}**Be carefull** is a warning{{% /alert %}} diff --git a/exampleSite/content/shortcodes/attachments/_index.md b/exampleSite/content/shortcodes/attachments/_index.md index c465e75..6d34496 100644 --- a/exampleSite/content/shortcodes/attachments/_index.md +++ b/exampleSite/content/shortcodes/attachments/_index.md @@ -46,9 +46,9 @@ For example: ## Demo ### List of attachments ending in pdf or mp4 - +``` {{%/*attachments title="Related files" pattern=".*(pdf|mp4)"/*/%}} - +``` renders as {{%attachments title="Related files" pattern=".*(pdf|mp4)"/%}} diff --git a/exampleSite/content/shortcodes/button/_index.md b/exampleSite/content/shortcodes/button/_index.md index 59d498f..5ed2cc2 100644 --- a/exampleSite/content/shortcodes/button/_index.md +++ b/exampleSite/content/shortcodes/button/_index.md @@ -18,14 +18,15 @@ Display an actionable button in your page. The inner text you place in short code will be displayed as the _button text_ ## Demo - +``` {{</* button href="https://google.com" */>}} go to google {{</* /button */>}} {{</* button href="https://google.com" theme="success" */>}} Success {{</* /button */>}} {{</* button href="https://google.com" theme="info" */>}} Info {{</* /button */>}} {{</* button href="https://google.com" theme="warning" */>}} Warning {{</* /button */>}} {{</* button href="https://google.com" theme="danger" */>}} Danger ! {{</* /button */>}} {{</* button href="https://google.com" theme="default" */>}} Danger ! {{</* /button */>}} - +``` + {{<button href="https://google.com" >}} go to google {{< /button >}} {{<button href="https://google.com" theme="success">}} Success {{< /button >}} {{<button href="https://google.com" theme="info">}} Info {{< /button >}} diff --git a/exampleSite/content/shortcodes/excerpt-include/_index.md b/exampleSite/content/shortcodes/excerpt-include/_index.md index 674cfb5..0f7ccc9 100644 --- a/exampleSite/content/shortcodes/excerpt-include/_index.md +++ b/exampleSite/content/shortcodes/excerpt-include/_index.md @@ -17,7 +17,9 @@ Before you can use this shortcode, the excerpt must have been defined using the ## Demo The paragraph below shows an example of an Excerpt Include shortcode, containing content from an excerpt which we have defined on the Excerpt shortcode page. On the Excerpt Include shortcode below, we have set the options to show both the title of the page and the panel surrounding the content. +``` {{%/*excerpt-include filename="shortcodes/excerpt/_index.md" panel="From excerpt page" /*/%}} +``` {{%excerpt-include filename="shortcodes/excerpt/_index.md" panel="From excerpt page" /%}} diff --git a/exampleSite/content/shortcodes/excerpt/_index.md b/exampleSite/content/shortcodes/excerpt/_index.md index 1c720b2..5878c55 100644 --- a/exampleSite/content/shortcodes/excerpt/_index.md +++ b/exampleSite/content/shortcodes/excerpt/_index.md @@ -15,7 +15,7 @@ The Excerpt shortcode is used to mark a part of a page's content for re-use. Def | hidden | "false" | Controls whether the page content contained in the Excerpt shortcode placeholder is displayed on the page.{{%alert warning%}}Note that this option affects only the page that contains the Excerpt shortcode. It does not affect any pages where the content is reused.{{%/alert%}} | ## Demo - +``` {{%/*excerpt*/%}} Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, @@ -24,6 +24,7 @@ The Excerpt shortcode is used to mark a part of a page's content for re-use. Def cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. {{%/* /excerpt*/%}} +``` {{%excerpt%}} Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod diff --git a/exampleSite/content/shortcodes/expand/_index.md b/exampleSite/content/shortcodes/expand/_index.md index 361a416..17100d8 100644 --- a/exampleSite/content/shortcodes/expand/_index.md +++ b/exampleSite/content/shortcodes/expand/_index.md @@ -18,20 +18,20 @@ proident, sunt in culpa qui officia deserunt mollit anim id est laborum.{{%/expa this shortcode takes exactly one optional parameter to define the text that appears next to the expand/collapse icon. (default is "Expand me...") - +``` {{%/*expand "Is this docport theme rocks ?" */%}}Yes !.{{%/* /expand*/%}} - +``` {{%expand "Is this docport theme rocks ?" %}}Yes !{{% /expand%}} # Demo - +``` {{%/*expand*/%}}Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.{{%/* /expand*/%}} - +``` {{%expand%}}Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, diff --git a/exampleSite/content/shortcodes/icon/_index.md b/exampleSite/content/shortcodes/icon/_index.md index f039b43..b194066 100644 --- a/exampleSite/content/shortcodes/icon/_index.md +++ b/exampleSite/content/shortcodes/icon/_index.md @@ -24,9 +24,9 @@ setting only the name as argument works too : `{{</*icon film*/>}}` instead of ` {{%/alert%}} ## Demo - +``` {{</* icon name="save" size="64px" */>}} - +``` {{<icon name="save" size="64px">}} . diff --git a/i18n/en.toml b/i18n/en.toml index 35dd8bd..56c7085 100644 --- a/i18n/en.toml +++ b/i18n/en.toml @@ -48,4 +48,4 @@ other= "Home" other= "Next page" [table-of-contents] -other= "Table of contents"
\ No newline at end of file +other= "What's on this page"
\ No newline at end of file diff --git a/i18n/fr.toml b/i18n/fr.toml index 3452be7..84da357 100644 --- a/i18n/fr.toml +++ b/i18n/fr.toml @@ -48,4 +48,4 @@ other= "Accueil" other= "Contenu suivant" [table-of-contents] -other= "Sommaire"
\ No newline at end of file +other= "Contenu de la page"
\ No newline at end of file diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html index befda08..d5a1abb 100644 --- a/layouts/_default/baseof.html +++ b/layouts/_default/baseof.html @@ -1,9 +1,21 @@ +{{- $redirectURL := "" }} +{{ with .Params.redirect}} + {{ if or (hasPrefix . "http:") (hasPrefix . "https:") }} + {{ $redirectURL = . }} + {{ else }} + {{ $redirectURL = relref $ .}} + {{ end }} +{{ end }} <!DOCTYPE html> <html> <head> <title>{{ block "title" . }}{{ end }}</title> {{ partial "html-head.html" . }} + {{if ne $redirectURL "" }} + <meta http-equiv="refresh" content="0;{{ $redirectURL }}"> + {{end}} </head> + <body data-url="{{ .RelPermalink }}" class=" @@ -14,7 +26,7 @@ {{if .Params.hide_toc}}hidetoc {{end -}} {{if .Params.hide_footer}}hidefooter {{end -}} "> -<!-- +<!-- <style type="text/css"> #debug{ display: -webkit-box; @@ -37,12 +49,17 @@ overflow: auto; } </style> -<pre id="debug"> - {{ printf "%#v" resources }} -</pre> + <pre id="debug"> + {{ printf "%#v" $redirectURL }} +</pre> --> -{{ if eq .Params.layout "raw" }} +{{ if ne $redirectURL ""}} + <script type="text/javascript"> + window.location = '{{ $redirectURL }}' + </script> + <a href="{{ $redirectURL }}">go to {{ $redirectURL }}</a> +{{ else if eq .Params.layout "raw" }} {{- .Content -}} {{ else }} <header style=""> diff --git a/layouts/partials/body-article-sidepage.html b/layouts/partials/body-article-sidepage.html index e49376d..5a4aa75 100644 --- a/layouts/partials/body-article-sidepage.html +++ b/layouts/partials/body-article-sidepage.html @@ -1,4 +1,4 @@ -{{- partial "_mdinclude.html" (dict "name" "_article-sidepage-before" "context" .) -}} +{{- partial "_mdinclude.html" (dict "name" "_layout/article-sidebar-before/_index" "context" .) -}} <div class="actions"> </div> <div class="TableOfContents"> @@ -10,4 +10,4 @@ </nav> {{ .TableOfContents }} </div> -{{- partial "_mdinclude.html" (dict "name" "_article-sidepage-after" "context" .) -}}
\ No newline at end of file +{{- partial "_mdinclude.html" (dict "name" "_layout/article-sidebar-after/_index" "context" .) -}}
\ No newline at end of file |
