From c08d263aeedf0470c02d7a6c88000c108412316f Mon Sep 17 00:00:00 2001 From: vjeantet Date: Sun, 30 Aug 2020 18:15:15 +0200 Subject: update documentation --- assets/sass/main.scss | 1 + exampleSite/config-template.toml | 69 ++++++++++ .../00-adding-content/_index.md | 102 +++++++++++++++ .../00-adding-content/myslide/index.md | 48 +++++++ .../00-adding-content/page-images/_index.md | 31 +++++ .../00-adding-content/page-images/image.jpeg | Bin 0 -> 90747 bytes .../00-adding-content/page-slide/_index.md | 142 +++++++++++++++++++++ .../00-adding-content/subpages.png | Bin 0 -> 33121 bytes .../01-homepage/_index.md | 43 +++++++ .../02-navigation-search/_index.md | 17 +++ .../02-navigation-search/menu/_index.md | 85 ++++++++++++ .../02-navigation-search/menu/screenshot.png | Bin 0 -> 34061 bytes .../02-navigation-search/screenshot.png | Bin 0 -> 115468 bytes .../02-navigation-search/search/_index.md | 24 ++++ .../02-navigation-search/thefooter/_index.md | 31 +++++ .../02-navigation-search/thefooter/screenshot.png | Bin 0 -> 84545 bytes .../02-navigation-search/theheader/_index.md | 61 +++++++++ .../02-navigation-search/theheader/screenshot.png | Bin 0 -> 18132 bytes .../02-navigation-search/toc/_index.md | 47 +++++++ .../02-navigation-search/toc/screenshot.png | Bin 0 -> 27271 bytes .../03-look-and-feel/_index.md | 14 ++ .../03-look-and-feel/colors/_index.md | 46 +++++++ .../03-look-and-feel/colors/color001.png | Bin 0 -> 156181 bytes .../03-look-and-feel/colors/color002.png | Bin 0 -> 154953 bytes .../03-look-and-feel/colors/color003.png | Bin 0 -> 150486 bytes .../03-look-and-feel/colors/color004.png | Bin 0 -> 155456 bytes .../03-look-and-feel/colors/color005.png | Bin 0 -> 164995 bytes .../03-look-and-feel/colors/color006.png | Bin 0 -> 164758 bytes .../03-look-and-feel/colors/rainbow.gif | Bin 0 -> 75687 bytes .../03-look-and-feel/css-js/_index.md | 49 +++++++ .../03-look-and-feel/disable/_index.md | 16 +++ .../03-look-and-feel/disable/chevrons.png | Bin 0 -> 10908 bytes .../04-shortcodes/_index.md | 10 ++ .../content/content-and-customization/_index.md | 7 + exampleSite/content/content-organisation/_index.md | 98 -------------- .../content-organisation/customize-style/_index.md | 58 --------- .../customize-style/colors/_index.md | 31 ----- .../customize-style/disable/_index.md | 19 --- .../customize-style/disable/test.md | 18 --- .../customize-style/disable/test2.md | 18 --- .../customize-style/theme-variants/_index.md | 36 ------ .../customize-style/themestyle/_index.md | 26 ---- .../content-organisation/extramenu/_index.md | 31 ----- .../content-organisation/placeholders/_index.md | 15 --- .../placeholders/header/_index.md | 19 --- .../placeholders/menu/_index.md | 33 ----- .../placeholders/thefooter/_index.md | 17 --- .../placeholders/toc/_index.md | 28 ---- .../content/content-organisation/subpages.png | Bin 33121 -> 0 bytes exampleSite/content/create-page/_index.md | 63 --------- .../create-page/control-page-menu/_index.md | 37 ------ exampleSite/content/create-page/myslide/index.md | 48 ------- .../content/create-page/page-images/_index.md | 31 ----- .../content/create-page/page-slide/_index.md | 142 --------------------- .../create-page/set-your-homepage/_index.md | 27 ---- .../content/docport-theme/credits/_index.md | 2 +- exampleSite/content/examples/_index.md | 9 ++ .../examples/page with raw content/_index.md | 21 +++ .../content/examples/page without footer/_index.md | 20 +++ .../content/examples/page without header/_index.md | 21 +++ .../page without sidebar and toc/_index.md | 21 +++ .../content/examples/page without toc/_index.md | 20 +++ exampleSite/content/getting-start/_index.md | 2 + .../content/getting-start/configuration/_index.md | 55 ++------ .../installation/As-git-clone/_index.md | 20 +++ .../content/getting-start/installation/_index.md | 52 ++------ .../installation/direct copy/_index.md | 24 ++++ exampleSite/content/search/_index.md | 15 --- exampleSite/content/shortcodes/alert/_index.md | 3 +- .../content/shortcodes/attachments/_index.md | 4 +- exampleSite/content/shortcodes/button/_index.md | 5 +- .../content/shortcodes/excerpt-include/_index.md | 2 + exampleSite/content/shortcodes/excerpt/_index.md | 3 +- exampleSite/content/shortcodes/expand/_index.md | 8 +- exampleSite/content/shortcodes/icon/_index.md | 4 +- i18n/en.toml | 2 +- i18n/fr.toml | 2 +- layouts/_default/baseof.html | 27 +++- layouts/partials/body-article-sidepage.html | 4 +- 79 files changed, 1069 insertions(+), 915 deletions(-) create mode 100644 exampleSite/config-template.toml create mode 100644 exampleSite/content/content-and-customization/00-adding-content/_index.md create mode 100644 exampleSite/content/content-and-customization/00-adding-content/myslide/index.md create mode 100644 exampleSite/content/content-and-customization/00-adding-content/page-images/_index.md create mode 100644 exampleSite/content/content-and-customization/00-adding-content/page-images/image.jpeg create mode 100644 exampleSite/content/content-and-customization/00-adding-content/page-slide/_index.md create mode 100644 exampleSite/content/content-and-customization/00-adding-content/subpages.png create mode 100644 exampleSite/content/content-and-customization/01-homepage/_index.md create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/_index.md create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/menu/_index.md create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/menu/screenshot.png create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/screenshot.png create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/search/_index.md create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/thefooter/_index.md create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/thefooter/screenshot.png create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/theheader/_index.md create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/theheader/screenshot.png create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/toc/_index.md create mode 100644 exampleSite/content/content-and-customization/02-navigation-search/toc/screenshot.png create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/_index.md create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/_index.md create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/color001.png create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/color002.png create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/color003.png create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/color004.png create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/color005.png create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/color006.png create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/colors/rainbow.gif create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/css-js/_index.md create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/disable/_index.md create mode 100644 exampleSite/content/content-and-customization/03-look-and-feel/disable/chevrons.png create mode 100644 exampleSite/content/content-and-customization/04-shortcodes/_index.md create mode 100644 exampleSite/content/content-and-customization/_index.md delete mode 100644 exampleSite/content/content-organisation/_index.md delete mode 100644 exampleSite/content/content-organisation/customize-style/_index.md delete mode 100644 exampleSite/content/content-organisation/customize-style/colors/_index.md delete mode 100644 exampleSite/content/content-organisation/customize-style/disable/_index.md delete mode 100644 exampleSite/content/content-organisation/customize-style/disable/test.md delete mode 100644 exampleSite/content/content-organisation/customize-style/disable/test2.md delete mode 100644 exampleSite/content/content-organisation/customize-style/theme-variants/_index.md delete mode 100644 exampleSite/content/content-organisation/customize-style/themestyle/_index.md delete mode 100644 exampleSite/content/content-organisation/extramenu/_index.md delete mode 100644 exampleSite/content/content-organisation/placeholders/_index.md delete mode 100644 exampleSite/content/content-organisation/placeholders/header/_index.md delete mode 100644 exampleSite/content/content-organisation/placeholders/menu/_index.md delete mode 100644 exampleSite/content/content-organisation/placeholders/thefooter/_index.md delete mode 100644 exampleSite/content/content-organisation/placeholders/toc/_index.md delete mode 100644 exampleSite/content/content-organisation/subpages.png delete mode 100644 exampleSite/content/create-page/_index.md delete mode 100644 exampleSite/content/create-page/control-page-menu/_index.md delete mode 100644 exampleSite/content/create-page/myslide/index.md delete mode 100644 exampleSite/content/create-page/page-images/_index.md delete mode 100644 exampleSite/content/create-page/page-slide/_index.md delete mode 100644 exampleSite/content/create-page/set-your-homepage/_index.md create mode 100644 exampleSite/content/examples/_index.md create mode 100644 exampleSite/content/examples/page with raw content/_index.md create mode 100644 exampleSite/content/examples/page without footer/_index.md create mode 100644 exampleSite/content/examples/page without header/_index.md create mode 100644 exampleSite/content/examples/page without sidebar and toc/_index.md create mode 100644 exampleSite/content/examples/page without toc/_index.md create mode 100644 exampleSite/content/getting-start/installation/As-git-clone/_index.md create mode 100644 exampleSite/content/getting-start/installation/direct copy/_index.md delete mode 100644 exampleSite/content/search/_index.md 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. +![](subpages.png?height=60px&classes=border,shadow) + + +## 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/content-and-customization/00-adding-content/myslide/index.md b/exampleSite/content/content-and-customization/00-adding-content/myslide/index.md new file mode 100644 index 0000000..1f611bc --- /dev/null +++ b/exampleSite/content/content-and-customization/00-adding-content/myslide/index.md @@ -0,0 +1,48 @@ ++++ +title = "My Slide ! fullscreen" +date = "2017-04-24T18:36:24+02:00" +type="slide" +hidden=true + +theme = "league" +[revealOptions] +transition= 'concave' +controls= true +progress= true +history= false +center= true ++++ + +# In the morning + +___ + +## Getting up + +- Turn off alarm +- Get out of bed + +___ + +## Breakfast + +- Eat eggs +- Drink coffee + +--- + +# In the evening + +___ + +## Dinner + +- Eat spaghetti +- Drink wine + +___ + +## Going to sleep + +- Get in bed +- Count sheep \ No newline at end of file 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. +``` + ![myImage](image.jpeg) +``` +![myImage](image.jpeg) + +## Resizing image + +Add HTTP parameters `width` and/or `height` to the link image to resize the image. Values are CSS values (default is `auto`). + +``` + ![myImage](image.jpeg?height=80px) +``` +![myImage](image.jpeg?height=80px) + + +## 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. +``` + ![myImage](image.jpeg?classes=border,shadow) +``` +![myImage](image.jpeg?classes=border,shadow) 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 new file mode 100644 index 0000000..08f2e1d Binary files /dev/null and b/exampleSite/content/content-and-customization/00-adding-content/page-images/image.jpeg differ diff --git a/exampleSite/content/content-and-customization/00-adding-content/page-slide/_index.md b/exampleSite/content/content-and-customization/00-adding-content/page-slide/_index.md new file mode 100644 index 0000000..957118c --- /dev/null +++ b/exampleSite/content/content-and-customization/00-adding-content/page-slide/_index.md @@ -0,0 +1,142 @@ ++++ +title = "As a SlideDeck" +description = "" +date = "2017-04-24T18:36:24+02:00" +weight = 90 + + +hide_header=false +hide_nav=false +hide_breadcrumb=false +hide_toc=false +hide_footer=false + ++++ + +A basic .md file can be rendered as a reveal.js presentation full screen. + +{{% notice %}} +**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 to consider a page as a slidedeck, just add a `type="slide"`in then frontmatter of your page. + +```toml ++++ +type="slide" ++++ +``` + + +{{%alert success%}}**Tip :** You can, also, **embed presentation in a page** as a small box, using the [revealjs]({{% relref "shortcodes/revealjs/_index.md"%}}) shortcode in your md file.{{%/alert%}} + + +## Formating your content +Use your common Markdown syntax you use in Hugo, don't forget, you can put html tags too. + +{{%notice info %}} Special syntax (in html comment) is available for adding attributes to Markdown elements. This is useful for fragments, amongst other things. +{{%/notice%}} + +Please read the [{{%icon book%}} doc from hakimel](https://github.com/hakimel/reveal.js/#instructions) + + +## Presentation options +In the frontmatter of your page file, set **type** and **revealOptions** params + +Your content will be served as a fullscreen revealjs presentation and revealOptions will be used to ajust its behaviour. +```toml + +++ + title = "Test slide" + type="slide" + + theme = "league" + [revealOptions] + transition= 'concave' + controls= true + progress= true + history= true + center= true + +++ +``` +[read more about reveal options here](https://github.com/hakimel/reveal.js/#configuration) + + +## Slide Delimiters +When creating the content for your slideshow presentation within content markdown file you need to be able to distinguish between one slide and the next. This is achieved very simply using a convention within Markdown that indicates the start of each new slide. + +As both horizontal and vertical slides are supported by reveal.js each has it's own unique delimiter. + +To denote the start of a horizontal slide simply add the following delimiter (dashes) in your Markdown: + +```md + --- +``` + + +To denote the start of a vertical slide simply add the following delimiter (underscores) in your Markdown: +```md + ___ +``` + +By using a combination of horizontal and vertical slides you can customize the navigation within your slideshow presentation. Typically vertical slides are used to present information below a top-level horizontal slide. + + + +For example, a very simple slideshow presentation can be created as follows + +```md ++++ + +title = "test" +date = "2017-04-24T18:36:24+02:00" +type="slide" + +theme = "league" +[revealOptions] +transition= 'concave' +controls= true +progress= true +history= true +center= true ++++ + +# In the morning + +___ + +## Getting up + +- Turn off alarm +- Get out of bed + +___ + +## Breakfast + +- Eat eggs +- Drink coffee + +--- + +# In the evening + +___ + +## Dinner + +- Eat spaghetti +- Drink wine + +___ + +## Going to sleep + +- Get in bed +- Count sheep + +``` + +[{{%icon aspect_ratio%}} click here to view this page rendered]({{%relref "myslide.md"%}}) diff --git a/exampleSite/content/content-and-customization/00-adding-content/subpages.png b/exampleSite/content/content-and-customization/00-adding-content/subpages.png new file mode 100644 index 0000000..528b828 Binary files /dev/null and b/exampleSite/content/content-and-customization/00-adding-content/subpages.png differ 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" ++++ +
+ Hello +
+``` + 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" %}} + +![footer](screenshot.png?classes=border,shadow) 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 + +![header](screenshot.png?classes=border,shadow) + +## 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 = "
" + +# 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 new file mode 100644 index 0000000..71cfa83 Binary files /dev/null and b/exampleSite/content/content-and-customization/02-navigation-search/menu/screenshot.png differ diff --git a/exampleSite/content/content-and-customization/02-navigation-search/screenshot.png b/exampleSite/content/content-and-customization/02-navigation-search/screenshot.png new file mode 100644 index 0000000..91bd297 Binary files /dev/null and b/exampleSite/content/content-and-customization/02-navigation-search/screenshot.png differ 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 ! + +![footer](screenshot.png?classes=border,shadow) + +## 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 new file mode 100644 index 0000000..f503504 Binary files /dev/null and b/exampleSite/content/content-and-customization/02-navigation-search/thefooter/screenshot.png differ 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. + +![header](screenshot.png?classes=border,shadow) + +## 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 new file mode 100644 index 0000000..ec53b38 Binary files /dev/null and b/exampleSite/content/content-and-customization/02-navigation-search/theheader/screenshot.png differ 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 + +![header](screenshot.png?classes=border,shadow) + +## 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 new file mode 100644 index 0000000..c259550 Binary files /dev/null and b/exampleSite/content/content-and-customization/02-navigation-search/toc/screenshot.png differ 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 +![](rainbow.gif?height=64px) +Comment theses two params in your config.toml, you will have random colors on each build... :) + + + +Examples of random colors + +![](color001.png?height=300px&classes=border,shadow) +![](color002.png?height=300px&classes=border,shadow) +![](color003.png?height=300px&classes=border,shadow) +![](color004.png?height=300px&classes=border,shadow) +![](color005.png?height=300px&classes=border,shadow) +![](color006.png?height=300px&classes=border,shadow) 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 new file mode 100644 index 0000000..636f5df Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color001.png differ 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 new file mode 100644 index 0000000..2195929 Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color002.png differ 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 new file mode 100644 index 0000000..b97babf Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color003.png differ 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 new file mode 100644 index 0000000..464ed4a Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color004.png differ 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 new file mode 100644 index 0000000..755e7d6 Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color005.png differ 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 new file mode 100644 index 0000000..3b363ec Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/colors/color006.png differ 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 new file mode 100644 index 0000000..27bf1d6 Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/colors/rainbow.gif differ diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/css-js/_index.md b/exampleSite/content/content-and-customization/03-look-and-feel/css-js/_index.md new file mode 100644 index 0000000..52d4aed --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/css-js/_index.md @@ -0,0 +1,49 @@ ++++ +title="CSS & JS" +subpage=true + ++++ + +## Add custom CSS and JS into the \ part of each page : + +Create a file as `layouts/partials/head.html` + +```bash + content/ + layouts/ + └── partials/ + └── head.html +``` + +write your own content like : +```html + + +``` + +Then override the style your want to change in `static/css/custom.css` (in this case, to avoid altering the casing of titles): +```css +h2 { + text-transform: none; +} +``` + +And execute some additional JavaScript from `static/js/custom.js` (note that jQuery is already loaded by the theme): +```javascript +function tweakPage() { + // make some changes here +} + +$(tweakPage) +``` + +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 "02-navigation-search"%}}) + +## Overide existing CSS or JS + +Create the matching file in your static folder, hugo will use yours instead of the theme's one. + diff --git a/exampleSite/content/content-and-customization/03-look-and-feel/disable/_index.md b/exampleSite/content/content-and-customization/03-look-and-feel/disable/_index.md new file mode 100644 index 0000000..b35401f --- /dev/null +++ b/exampleSite/content/content-and-customization/03-look-and-feel/disable/_index.md @@ -0,0 +1,16 @@ ++++ +title = "Disable features" +subpage=true ++++ + +You can disable feature in docport by changing some params in `config.toml` + + +## Hide Next Page Chevrons + +![](chevrons.png?classes=border,shadow) + +```toml + [params] + 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 new file mode 100644 index 0000000..2d8a08b Binary files /dev/null and b/exampleSite/content/content-and-customization/03-look-and-feel/disable/chevrons.png differ 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. - - -![agence](subpages.png?height=80px&classes=border,shadow) - -## 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/_index.md b/exampleSite/content/content-organisation/customize-style/_index.md deleted file mode 100644 index 4979fb4..0000000 --- a/exampleSite/content/content-organisation/customize-style/_index.md +++ /dev/null @@ -1,58 +0,0 @@ -+++ -title = "Customize look and feel" -Weight=3 -+++ - -You can change the style and behavior of the theme without touching its source code. - -* 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 \ part of each page : - -Create a file as `layouts/partials/head.html` - -```bash - content/ - layouts/ - └── partials/ - └── head.html -``` - -write your own content like : -```html - - -``` - -Then override the style your want to change in `static/css/custom.css` (in this case, to avoid altering the casing of titles): -```css -h2 { - text-transform: none; -} -``` - -And execute some additional JavaScript from `static/js/custom.js` (note that jQuery is already loaded by the theme): -```javascript -function tweakPage() { - // make some changes here -} - -$(tweakPage) -``` - -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"%}}) - -## Overide existing CSS or JS - -Create the matching file in your static folder, hugo will use yours instead of the theme's one. - 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/_index.md b/exampleSite/content/content-organisation/customize-style/disable/_index.md deleted file mode 100644 index 07bd1a3..0000000 --- a/exampleSite/content/content-organisation/customize-style/disable/_index.md +++ /dev/null @@ -1,19 +0,0 @@ -+++ -title = "Disable features" -subpage=true -+++ - -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 -``` 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" -``` - -![green docport](/variant-gray.png) - -## Variant "gold" -``` -[params] -themeVariant = "gold" -``` - -![gold docport](/variant-gold.png) - -## Variant "green" -``` -[params] -themeVariant = "green"` -``` - -![green docport](/variant-green.png) \ 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" -``` - -![green docport](/variant-gray.png) - -## Style "flex" (work in progress) -``` -[params] -themeStyle = "flex" -``` - -![flex](/style-flex.png) \ 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 = "cloud_download 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/content-organisation/subpages.png b/exampleSite/content/content-organisation/subpages.png deleted file mode 100644 index 528b828..0000000 Binary files a/exampleSite/content/content-organisation/subpages.png and /dev/null differ 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="
" is set -head = "
" - -# 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/myslide/index.md b/exampleSite/content/create-page/myslide/index.md deleted file mode 100644 index 1f611bc..0000000 --- a/exampleSite/content/create-page/myslide/index.md +++ /dev/null @@ -1,48 +0,0 @@ -+++ -title = "My Slide ! fullscreen" -date = "2017-04-24T18:36:24+02:00" -type="slide" -hidden=true - -theme = "league" -[revealOptions] -transition= 'concave' -controls= true -progress= true -history= false -center= true -+++ - -# In the morning - -___ - -## Getting up - -- Turn off alarm -- Get out of bed - -___ - -## Breakfast - -- Eat eggs -- Drink coffee - ---- - -# In the evening - -___ - -## Dinner - -- Eat spaghetti -- Drink wine - -___ - -## Going to sleep - -- Get in bed -- Count sheep \ 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. - - ![agence](https://github.com/vjeantet/vjeantet.fr/raw/master/static/images/sgthon/C.jpg) - -![agence](https://github.com/vjeantet/vjeantet.fr/raw/master/static/images/sgthon/C.jpg) - -## Resizing image - -Add HTTP parameters `width` and/or `height` to the link image to resize the image. Values are CSS values (default is `auto`). - - - ![Hackathon](https://github.com/vjeantet/vjeantet.fr/raw/master/static/images/sgthon/C.jpg?height=80px) - -![agence](https://github.com/vjeantet/vjeantet.fr/raw/master/static/images/sgthon/C.jpg?height=80px) - - -## 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. - - ![s](https://github.com/vjeantet/vjeantet.fr/raw/master/static/images/sgthon/C.jpg?classes=border,shadow) - -![agence](https://github.com/vjeantet/vjeantet.fr/raw/master/static/images/sgthon/C.jpg?classes=border,shadow) diff --git a/exampleSite/content/create-page/page-slide/_index.md b/exampleSite/content/create-page/page-slide/_index.md deleted file mode 100644 index b5cfbc2..0000000 --- a/exampleSite/content/create-page/page-slide/_index.md +++ /dev/null @@ -1,142 +0,0 @@ -+++ -title = "As a SlideDeck" -description = "" -date = "2017-04-24T18:36:24+02:00" -weight = 90 -subpage = true - -hide_header=false -hide_nav=false -hide_breadcrumb=false -hide_toc=false -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/). -\ -[{{%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. - -```toml -+++ -type="slide" -+++ -``` - - -{{%alert success%}}**Tip :** You can, also, **embed presentation in a page** as a small box, using the [revealjs]({{% relref "shortcodes/revealjs/_index.md"%}}) shortcode in your md file.{{%/alert%}} - - -## Formating your content -Use your common Markdown syntax you use in Hugo, don't forget, you can put html tags too. - -{{%notice info %}} Special syntax (in html comment) is available for adding attributes to Markdown elements. This is useful for fragments, amongst other things. -{{%/notice%}} - -Please read the [{{%icon book%}} doc from hakimel](https://github.com/hakimel/reveal.js/#instructions) - - -## Presentation options -In the frontmatter of your page file, set **type** and **revealOptions** params - -Your content will be served as a fullscreen revealjs presentation and revealOptions will be used to ajust its behaviour. -```toml - +++ - title = "Test slide" - type="slide" - - theme = "league" - [revealOptions] - transition= 'concave' - controls= true - progress= true - history= true - center= true - +++ -``` -[read more about reveal options here](https://github.com/hakimel/reveal.js/#configuration) - - -## Slide Delimiters -When creating the content for your slideshow presentation within content markdown file you need to be able to distinguish between one slide and the next. This is achieved very simply using a convention within Markdown that indicates the start of each new slide. - -As both horizontal and vertical slides are supported by reveal.js each has it's own unique delimiter. - -To denote the start of a horizontal slide simply add the following delimiter (dashes) in your Markdown: - -```md - --- -``` - - -To denote the start of a vertical slide simply add the following delimiter (underscores) in your Markdown: -```md - ___ -``` - -By using a combination of horizontal and vertical slides you can customize the navigation within your slideshow presentation. Typically vertical slides are used to present information below a top-level horizontal slide. - - - -For example, a very simple slideshow presentation can be created as follows - -```md -+++ - -title = "test" -date = "2017-04-24T18:36:24+02:00" -type="slide" - -theme = "league" -[revealOptions] -transition= 'concave' -controls= true -progress= true -history= true -center= true -+++ - -# In the morning - -___ - -## Getting up - -- Turn off alarm -- Get out of bed - -___ - -## Breakfast - -- Eat eggs -- Drink coffee - ---- - -# In the evening - -___ - -## Dinner - -- Eat spaghetti -- Drink wine - -___ - -## Going to sleep - -- Get in bed -- Count sheep - -``` - -[{{%icon aspect_ratio%}} click here to view this page rendered]({{%relref "myslide.md"%}}) 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" -+++ -
- Hello -
-``` - 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
- @matcornic + @matcornic
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 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 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:
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. - -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 = "" -``` -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/). -## 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: "star_border " ---- -{{%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.
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 - +``` {{}} go to google {{}} {{}} Success {{}} {{}} Info {{}} {{}} Warning {{}} {{}} Danger ! {{}} {{}} Danger ! {{}} - +``` + {{