From 3e48e5bf1fbc4623cd336064e5ca34762ed14e1f Mon Sep 17 00:00:00 2001 From: Patrick Collins Date: Sun, 15 Oct 2017 19:18:38 -0400 Subject: Update docs (#62) * Update docs, particularly README.md --- LICENSE.md | 2 +- README.md | 221 ++++++++++++++++++++++++++++++++++++++------------ images/screenshot.png | Bin 444978 -> 307330 bytes images/tn.png | Bin 182349 -> 0 bytes 4 files changed, 168 insertions(+), 55 deletions(-) delete mode 100644 images/tn.png diff --git a/LICENSE.md b/LICENSE.md index f4c4c0d..73f4792 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016 Julio Pescador +Copyright (c) 2017 Julio Pescador Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in diff --git a/README.md b/README.md index fe643da..68d9284 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,208 @@ # Hugo Future Imperfect -Future Imperfect is a responsive theme tailored for blogging. The name is no coincidence which is a port of [HTML5 UP's theme](http://html5up.net/future-imperfect). Some extra features have also been implemented to assist you. +Future Imperfect is a responsive theme tailored for blogging. The name is of no +coincidence, because it is a port of [HTML5 UP's theme](http://html5up.net/future-imperfect) +by the same name. In addition to the original features, there are more features +that have been added for you to utilize. ![Hugo Future Imperfect Screenshot](https://raw.githubusercontent.com/jpescador/hugo-future-imperfect/master/images/screenshot.png) -Check out this [site](https://jpescador.com) if you are interested in seeing a live example. +Check out this [site](https://themes.gohugo.io/theme/future-imperfect/) if you are +interested in seeing a live example. + +## Table of Contents + + + +- [Table of Contents](#table-of-contents) +- [Getting Started](#getting-started) + - [exampleSite](#examplesite) + - [config.toml](#configtoml) + - [Hugo's Built-In Server](#hugos-built-in-server) +- [Shortcodes](#shortcodes) + - [fancybox](#fancybox) + - [img-post](#img-post) + - [img-fit](#img-fit) + - [url-link](#url-link) +- [About the Author](#about-the-author) +- [License](#license) + + ## Getting Started Run the following commands in your Hugo site directory: - mkdir themes - cd themes - git clone https://github.com/jpescador/hugo-future-imperfect.git +```Shell Session +mkdir themes +cd themes +git clone https://github.com/jpescador/hugo-future-imperfect.git +``` + +You will then have access to the theme at _themes/hugo-future-imperfect_ from within +your project folder. + +### exampleSite + +Within the hugo-future-imperfect folder, there will be a folder in this theme called +_exampleSite_. The structure of the folder will look like this: + +``` +exampleSite +├── config.toml +├── staticman.yml +├── content + └── about + | └── _index.md + └── blog + │ ├── creating-a-new-theme.md + │ ├── goisforlovers.md + │ ├── hugoisforlovers.md + │ └── migrate-from-jekyll.md + └── contact + │ └── _index.md + └── itemized + │ ├── item1.md + │ ├── item2.md + │ ├── item3.md + │ └── item4.md + └── data + │ └── comments + │ └── .gitkeep + └── static + ├── css + │ └── add-on.css + ├── img + | ├── 2014 + | | ├── 04 + | | | ├── pic02.jpg + | | | └── pic03.jpg + | | └── 09 + | | └── pic01.jpg + | └── main + | └── logo.jpg + └── js + └── add-on.js +``` + +Copy _config.toml_ from _exampleSite_ to the root directory of your Hugo site. +If you want static comments hosted by [Staticman](https://staticman.net/), also +copy the _staticman.yml_. + +### config.toml + +This file is the main sorce of customization within the theme. Each parameter has +a comment included to explain its functionality. Typical usage of _true_ means to +turn a function on, while _false_ means to turn a function off. + +This file consists of six main sections. The first section contains the site wide +parameters innate to Hugo. The second section, _[params]_, contains site wide +parameter that are custom to the _hugo-future-imperfect_ theme. The third section, +_[params.staticman]_ controls how staticman comments interact with your repository. +The fourth section, _[params.intro]_ and _[params.postAmount]_, control aspects +of the sidebar. The fifth section, _[[menu.main]]_, sets the navigation menu items. +Lastly, the sixth section, _[social]_, allows you to easily link to, and include, +various social platforms. + +### Hugo's Built-In Server + +Run the following command to start a local server and to view a live version of +the website: + +```Shell Session +hugo server +``` + +You will then be able to view your live website at [localhost:1313](http://localhost:1313). + +## Shortcodes +In addition to the native [Hugo shortcodes](https://gohugo.io/extras/shortcodes/), +the theme also includes the following codes that I hope you find useful: +fancybox, img-post, img-fit, and url-link. -A folder called hugo-future-imperfect will be created. Navigate to this folder. +### fancybox +[Fancybox](http://fancyapps.com/fancybox/3/) is a jQuery lightbox script for displaying images, videos and more. It is touch +enabled, responsive and fully customizable. The commands are shown below: -## exampleSite +**Named** +```Markdown +{{< fancybox path="path" file="file" caption="caption" gallery="gallery" >}} +``` -There will be a folder in this theme called exampleSite. The structure of the folder will look something this: +**Positional** +```Markdown +{{< fancybox "path" "file" "caption" "gallery" >}} +``` - exampleSite - ├── config.toml - ├── content - └── about - | └── _index.md - └── blog - │ ├── creating-a-new-theme.md - │ ├── goisforlovers.md - │ ├── hugoisforlovers.md - │ └── migrate-from-jekyll.md - └── contact - │ └── _index.md - └── itemized - └── item1.md - └── item2.md - ... +Please refer to _layouts/shortcodes/fancybox.html_ for more details on the function. -Copy the config file from exampleSite to the root directory of your Hugo site. +Credit: [pacollins] -## The Config File +--- -The file contains comments on the functionality for each param. Please see the file for more information. +### img-post +Add an image which can be aligned center, left, or right. The commands are shown +below: -## Shortcodes -The theme also contains the following [shortcodes](https://gohugo.io/extras/shortcodes/) that I hope you find useful: img-post, img-fit, and url-link. +**Named** +```Markdown +{{< img-post path="date" file="filename.jpg" alt="Alt Text" type="left" >}} +``` -### Image post -img-post: allows the user to add an image which can be placed in the center, to the left, or the right. The commands are shown below: +**Positional** +```Markdown +{{< img-post "title" "filename.jpg" "Alt Text" "left" >}} +``` - - Named - {{< img-post path="date" file="filename.jpg" alt="Alt Text" type="left" >}} +Please refer to _layouts/shortcodes/img-post.html_ for more details on the function. - - Positional - {{< img-post "title" "filename.jpg" "Alt Text" "left" >}} +Credit: [jpescador] -Please refer to the img-post shortcode file for more information on the parameters +--- -### Multiple Image Post -img-fit: allows user to insert multiple images with the ability to create a gallery if needed. The command is shown below and is positional only: +### img-fit +Insert multiple images with the ability to create a gallery if needed. The command +is shown below: +**Positional Only** +```Markdown {{< img-fit - "4u" "pic04.jpg" "Alt text" - "4u" "pic05.jpg" "Alt text" - "4u$" "pic06.jpg" "Alt text" + "4u" "filename1.jpg" "Alt text 1" + "4u" "filename2.jpg" "Alt text 2" + "4u$" "filename3.jpg" "Alt text 3" "date" >}} +``` -Please refer to the img-fist shortcode file for more information on the parameters - +Please refer to _layouts/shortcodes/img-fit.html_ for more details on the function. -### URL link -url-link: create a hyperlink and add a target value to the link. _blank will be used by default if a target value is not set. The shortcode is positional only. +Credit: [jpescador] - {{< url-link "Hugo" "http://gohugo.io/" >}} +--- -Position 0 will be the link text. 1 will be the url and the last position will be value of the target attribute. +### url-link +Create a hyperlink and set a target value for the link. The default value is +`_blank`. The command is shown below: -## View the theme on Hugo's built-in server +**Positional Only** +```Markdown +{{< url-link "title" "www.link.com" "target">}} +``` -Run the following command to view the content of the website: +Please refer to _layouts/shortcodes/url-link.html_ for more details on the function. - hugo server - -You can now view the website at the following link, [localhost:1313](http://localhost:1313) +Credit: [jpescador] ## About the Author -Hugo Future Imperfect was ported and it's extra features were implemented by [Julio Pescador](https://jpescador.com) +Hugo Future Imperfect was ported by [Julio Pescador](https://jpescador.com). Extra +features implemented by the [project contributors](https://github.com/jpescador/hugo-future-imperfect/graphs/contributors). -Send me a [tweet](https://twitter.com/julio_pescador), @julio_pescador, if you like the theme and are using it for your own personal use. +Send Julio Pescador a tweet [@julio_pescador](https://twitter.com/julio_pescador), +if you like the theme and are using it for your own personal use. ## License This theme is released under the MIT license. Please read the [license](https://github.com/jpescador/hugo-future-imperfect/blob/master/LICENSE.md) for more information. + +[jpescador]: https://github.com/jpescador +[pacollins]: https://github.com/pacollins diff --git a/images/screenshot.png b/images/screenshot.png index b7cea3c..538bf4d 100644 Binary files a/images/screenshot.png and b/images/screenshot.png differ diff --git a/images/tn.png b/images/tn.png deleted file mode 100644 index d6800f2..0000000 Binary files a/images/tn.png and /dev/null differ -- cgit v1.2.3