diff options
| author | Thibaud Lepretre <thibaud.lepretre@gmail.com> | 2019-07-01 17:24:16 +0300 |
|---|---|---|
| committer | Thibaud Lepretre <thibaud.lepretre@gmail.com> | 2019-07-01 17:24:16 +0300 |
| commit | 5b70b1c8566cbadf346709c9d967d0bb68bb966a (patch) | |
| tree | 18056d7a5d7ae75052efdde49bfcf85c0b6f816d /docs | |
| parent | d24365653002414f37d75fc6692ad8b135f3844b (diff) | |
Remove grunt from doc, prefer using npm
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/developer.md | 46 | ||||
| -rw-r--r-- | docs/user.md | 142 |
2 files changed, 93 insertions, 95 deletions
diff --git a/docs/developer.md b/docs/developer.md index ac6caa5..d71391b 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -1,6 +1,6 @@ # Developer documentation # -This documentation will help you to understand Tranquilpeak Hugo theme code. +This documentation will help you to understand Tranquilpeak Hugo theme code. If you want to report a bug or ask a question, [create an issue](https://github.com/kakawait/hugo-tranquilpeak-theme/issues/new). @@ -45,16 +45,14 @@ If you want to report a bug or ask a question, [create an issue](https://github. 5. Install [requirements](#requirements) 6. Run `npm install` to install [NPM dependencies](#npm-dependencies) -If you want to configure the theme, please follow the [user documentation](https://github.com/kakawait/hugo-tranquilpeak-theme/blob/master/docs/user.md) +If you want to configure the theme, please follow the [user documentation](https://github.com/kakawait/hugo-tranquilpeak-theme/blob/master/docs/user.md) ## Code style ## -We use [ESLint](http://eslint.org) based on Google code style to maintain javascript code style. +We use [ESLint](http://eslint.org) based on Google code style to maintain javascript code style. Check code style with : ``` bash npm run lint -# or -grunt eslint ``` ## Code structure ## @@ -76,7 +74,7 @@ tranquilpeak <!--### Languages ### -Each files contains all labels used in the theme. +Each files contains all labels used in the theme. If you want to add a new language, duplicate an existing language file and replace all string by their translation.--> ### Views @@ -99,10 +97,10 @@ If you want to add a new language, duplicate an existing language file and repla #### Stylesheets -SCSS structure follow 7-1 pattern of [sass guidelines](http://sass-guidelin.es/#the-7-1-pattern) -If you want more information and to understand better this code, consult [sass guidelines](http://sass-guidelin.es/) +SCSS structure follow 7-1 pattern of [sass guidelines](http://sass-guidelin.es/#the-7-1-pattern) +If you want more information and to understand better this code, consult [sass guidelines](http://sass-guidelin.es/) -#### Images +#### Images ``` ├── images @@ -111,8 +109,8 @@ If you want more information and to understand better this code, consult [sass g |File|Description| |---|---| |cover.png|Default background cover of the blog| - -Contains all images of the theme. + +Contains all images of the theme. #### Javascript @@ -148,13 +146,13 @@ Contains all images of the theme. |smartresize.js|Debouncing function from [John Hann](https://github.com/unscriptable)| |tabbed-codeblocks.js|Animate tabs of tabbed code blocks| |tags-filter.js|Filter posts by using their tags on archives page : `/tags`| - -Each file correspond to a feature. - + +Each file correspond to a feature. + ## NPM scripts -Use `npm run <script_name>` to run one of these scripts. E.g : `npm run start` - +Use `npm run <script_name>` to run one of these scripts. E.g : `npm run start` + |`npm run ...`|Description| |---|---| |`start`|Build the theme once and rebuild after each change| @@ -163,14 +161,14 @@ Use `npm run <script_name>` to run one of these scripts. E.g : `npm run start` ## Grunt tasks ## -### Tasks structure - +### Tasks structure + ``` ├── tasks ├── config ├── register └── pipeline.js -``` +``` |File/folder|Description| |---|---| @@ -203,7 +201,7 @@ var tranquilpeakCssFilesToInject = [ On production environment, these javascript and stylesheets files are concatenate and minify in 1 javascript file and 1 stylesheet file and linked to their respective views -### Config tasks +### Config tasks |Task|Description| |---|---| @@ -233,14 +231,14 @@ When you run `grunt build` or `grunt buildProd` tasks, a `source/assets` folder ## Build ## -### Development environment +### Development environment -1. Run `npm run start` or `grunt default` and start coding :) +1. Run `npm run start` and start coding :) ### Production environment (before deploying your blog) -1. Run `npm run prod` or `grunt buildProd` to build the project with some optimization (concat and minify) to reduce number of HTTP requests and improve performance. +1. Run `npm run prod` to build the project with some optimization (concat and minify) to reduce number of HTTP requests and improve performance. ## Running ## -Run `hugo server` and start coding! :)
\ No newline at end of file +Run `hugo server` and start coding! :) diff --git a/docs/user.md b/docs/user.md index 8567bbf..4598463 100644 --- a/docs/user.md +++ b/docs/user.md @@ -1,12 +1,12 @@ # User documentation -A gorgeous responsive theme for Hugo blog framework +A gorgeous responsive theme for Hugo blog framework [](https://tranquilpeak.kakawait.com) Tranquilpeak theme is compatible with Hugo `v0.20`. -This documentation will help you to install hugo-tranquilpeak-theme and configure it to use all features which it provides. +This documentation will help you to install hugo-tranquilpeak-theme and configure it to use all features which it provides. If you want to report a bug or ask a question, [create an issue](https://github.com/kakawait/hugo-tranquilpeak-theme/issues/new). @@ -34,7 +34,7 @@ If you want to report a bug or ask a question, [create an issue](https://github. * [Google Analytics](#google-analytics) * [Exclude hostname (localhost) while writing articles](#exclude-hostname-localhost-while-writing-articles) * [Social cards](#social-cards) -- [Quick & easy modifications](#quick--easy-modifications) +- [Quick & easy modifications](#quick--easy-modifications) * [Prerequisites](#prerequisites) * [Change global style](#change-global-style) * [Change code coloration (Highlight.js theme)](#change-code-coloration-highlightjs-theme) @@ -50,7 +50,7 @@ If you want to report a bug or ask a question, [create an issue](https://github. * [Wide image](#wide-image) * [Fancybox](#fancybox) - [Writing pages](#writing-pages) -- [Running](#running) +- [Running](#running) ## General @@ -60,7 +60,7 @@ If you want to report a bug or ask a question, [create an issue](https://github. ## Features -**General features:** +**General features:** - Fully responsive - Optimized for tablets & mobiles @@ -71,8 +71,8 @@ If you want to report a bug or ask a question, [create an issue](https://github. - Support Open Graph protocol - Easily customizable (fonts, colors, layout elements, code coloration, etc..) - Support internationalization (i18) - -**Posts features:** + +**Posts features:** - Thumbnail image - Cover image @@ -82,9 +82,9 @@ If you want to report a bug or ask a question, [create an issue](https://github. - GitHub theme for code highlighting (customizable) - Image gallery - Tags for images (FancyBox), wide images, tabbed code blocks, highlighted text, alerts -- Table of contents - -**Integrated services:** +- Table of contents + +**Integrated services:** - Disqus - Google analytics @@ -142,12 +142,12 @@ by one of the following code (code is between `()`): - Spanish (`es`) - Vietnamese (`vi`) -If your language is not available, follow this guidelines (E.g : add swedish language (`sv-se`)) : +If your language is not available, follow this guidelines (E.g : add swedish language (`sv-se`)) : -1. Set `defaultContentLanguage` to `sv-se` in Hugo configuration file `config.{toml,yaml,json}` -2. Create `sv-se.yaml` file in `theme/tranquilpeak/i18n/` folder -3. Copy the content of `theme/tranquilpeak/i18n/en-us.yaml` and paste it to `sv-se.yml` file -4. Replace all strings in english by their translation in swedish +1. Set `defaultContentLanguage` to `sv-se` in Hugo configuration file `config.{toml,yaml,json}` +2. Create `sv-se.yaml` file in `theme/tranquilpeak/i18n/` folder +3. Copy the content of `theme/tranquilpeak/i18n/en-us.yaml` and paste it to `sv-se.yml` file +4. Replace all strings in english by their translation in swedish #### Menu translation @@ -176,13 +176,13 @@ ATTENTION: date format should respect `go` `Time` package syntax, please refer t **Moreover, if you are using fully named month (short named month like "jan", "feb", etc is not supported), month will be translated.** -Example: +Example: ```toml defaultContentLanguage = "fr-fr" ``` -"21 July 2006" will be output "21 Juillet 2006". +"21 July 2006" will be output "21 Juillet 2006". ### Define global keywords @@ -198,7 +198,7 @@ You can define keywords for search engines. These keywords will be added on all Backup your configuration: ```bash -cp config.{toml,yml,json} config.{toml,yml,json}.backup +cp config.{toml,yml,json} config.{toml,yml,json}.backup ``` Copy example configuration @@ -287,7 +287,7 @@ You can add groups of links and links much as you want. #### Header -The right link of the header is customizable. You can add a link (as an icon) at the right of the header instead of the author's gravatar image or author's picture. By default, author's gravatar or author's picture is displayed. +The right link of the header is customizable. You can add a link (as an icon) at the right of the header instead of the author's gravatar image or author's picture. By default, author's gravatar or author's picture is displayed. E.g to display a shortcut to open algolia search window : @@ -322,7 +322,7 @@ E.g to display a shortcut to open algolia search window : # Your google plus profile id. E.g : +ThibaudLepretre or 114625208755123718311 googlePlus = "+ThibaudLepretre" ``` - + | Variable | Description | |-----------------|--------------------------------------------------------------------------------------| | name | Your name | @@ -366,12 +366,12 @@ E.g to display a shortcut to open algolia search window : | customJS (_DEPRECATED see [Add custom JS or CSS using configuration](#add-custom-js-or-css-using-configuration)_) | Define files with js that override or extend the theme js: `customJS` = ["js/myscripts.js"]. | | syntaxHighlighter | Define which syntax highlighter you want to use (if not set syntax highlighting is disable) between `highlight.js` and `prism.js` | -E.g : -A category page look like this with `hierarchicalCategories = true` : - +E.g : +A category page look like this with `hierarchicalCategories = true` : + -The same page with `hierarchicalCategories = false`: - +The same page with `hierarchicalCategories = false`: + ##### Add custom JS or CSS using configuration @@ -408,7 +408,7 @@ Futhermore, even if previous syntax is still supported (`customJS = ["js/myscrip ```toml disqusShortname = -googleAnalytics = +googleAnalytics = ``` ```toml @@ -418,8 +418,8 @@ googleAnalytics = ```toml [params] - fbAdminIds = - fbAppId = + fbAdminIds = + fbAppId = ``` | Variable | Description | @@ -485,7 +485,7 @@ Tranquilpeak provides you 2 pages to display all posts title and date by tags, b While you are writing articles, you need to check the result a lot of times before deploying your site. If you have enable Google analytics service, Google will include all requests done, even when hostname is localhost and this can greatly skew the results. To overcome this, you have to add a filter on Google Analytics website. - + Follow these steps, to add new filter : 1. Sign in to your Google Analytics account @@ -520,27 +520,27 @@ If you want to change font families, font size, sidebar color, things like that, ### Change code coloration (Highlight.js theme) -Tranquilpeak integrate its own highlight.js theme inspired by GitHub. -Of course, you can replace it with an other theme found on highlight.js repository. Since Hexo use different CSS class names, all theme are not ready out of the box, but it is very easy to make them compatible. +Tranquilpeak integrate its own highlight.js theme inspired by GitHub. +Of course, you can replace it with an other theme found on highlight.js repository. Since Hexo use different CSS class names, all theme are not ready out of the box, but it is very easy to make them compatible. Follow these steps : 1. Get your theme here : [Highlight.js theme](https://github.com/isagalaev/highlight.js/tree/master/src/styles) or create yours 2. Follow guidelines in `src/scss/themes/hljs-custom.scss` file -3. Build the theme with `npm run prod` or `grunt buildProd`. Learn more about Grunt tasks : [Grunt tasks](https://github.com/LouisBarranqueiro/hexo-theme-tranquilpeak/blob/master/docs/developer.md#grunt-tasks) - +3. Build the theme with `npm run prod`. Learn more about Grunt tasks : [Grunt tasks](https://github.com/LouisBarranqueiro/hexo-theme-tranquilpeak/blob/master/docs/developer.md#grunt-tasks) + ## Writing posts -To write articles, you have to use Markdown language. [Here](https://guides.github.com/features/mastering-markdown/#examples) you can find the main basics of Markdown syntax. -Please note, there are many different versions of Markdown and some of them are not supported by Hugo. +To write articles, you have to use Markdown language. [Here](https://guides.github.com/features/mastering-markdown/#examples) you can find the main basics of Markdown syntax. +Please note, there are many different versions of Markdown and some of them are not supported by Hugo. **I STRONGLY recommend you to use a CDN to speed up loading of pages. There is many free CDN like Cloudinary or you can also use indirectly by using services like Google Photos.** ### Front-matter settings -Tranquilpeak introduces new variables to give you a lot of possibilities. - -Example : +Tranquilpeak introduces new variables to give you a lot of possibilities. + +Example : ```markdown disqusIdentifier: fdsF34ff34 @@ -593,19 +593,19 @@ summary: "This is a custom summary and does *not* appear in the post." |showActions|`true`: Show post actions (navigation, share links).| |summary|Custom excerpt text to show on the homepage.| -Example: -A post on index page will look like this with :`thumbnailImagePosition` set to `bottom`: - - -The same with : `thumbnailImagePosition` set to `right`: - - -The same with : `thumbnailImagePosition` set to `left`: - +Example: +A post on index page will look like this with :`thumbnailImagePosition` set to `bottom`: + + +The same with : `thumbnailImagePosition` set to `right`: + + +The same with : `thumbnailImagePosition` set to `left`: + ### Define post excerpt -Use: +Use: - `<!--more-->` to define post excerpt and keep the post excerpt in the post content - For a custom exerpt *not* in the post content, use the `summary` front-matter variable. Markdown syntax is supported. @@ -613,10 +613,10 @@ Use: ### Display table of contents As post excerpt feature enable with `<!--more-->` comment, you can display the table of contents of a post with `<!-- toc -->`. Place this comment where you want to display the table of content. - -Here is what looks like the table of contents generated: - - + +Here is what looks like the table of contents generated: + + ### Tags Tranquilpeak introduce new tags to display alert messages, images in full width and create beautiful galleries. @@ -627,14 +627,14 @@ Tranquilpeak introduce new tags to display alert messages, images in full width Alert tag is useful to highlight a content like a tips or a warning. Check it live here : [Alert tag demo](https://tranquilpeak.kakawait.com/2014/10/tags-plugins-showcase/#alert) -Syntax: +Syntax: ``` {{< alert [classes] >}} content {{< /alert >}} ``` -E.g: +E.g: ``` {{< alert danger no-icon >}} Here is a danger alert without icon @@ -651,14 +651,14 @@ Here is a danger alert without icon Highlight text tag is useful to highlight an interesting part in a text. Check it live here : [Highlight text tag demo](https://tranquilpeak.kakawait.com/2014/10/tags-plugins-showcase/#highlight-text) -Syntax: +Syntax: ``` {{< hl-text [classes] >}} content {{< /hl-text >}} -``` +``` -E.g: +E.g: ``` {{< hl-text danger >}} your highlighted text @@ -666,10 +666,10 @@ your highlighted text ``` |Argument|Description| -|---|---| +|---|---| |Classes|<strong>classes</strong> : <ul><li>red</li><li>green</li><li>blue</li><li>purple</li><li>orange</li><li>yellow</li><li>cyan</li><li>primary</li><li>success</li><li>warning</li><li>danger</li></ul>| - -**It's important to put the paragraph that contains highlight text tag inside** `<p>...</p>` + +**It's important to put the paragraph that contains highlight text tag inside** `<p>...</p>` **otherwise the following content may not be rendered.** #### Image @@ -687,7 +687,7 @@ E.g: ``` |Argument|Description| -|---|---| +|---|---| |classes (optional)|You can add css classes to stylize the image. Separate class with whitespace. Tranquilpeak integrate many css class to create nice effects : <ul><li><strong>fancybox</strong> : Generate a fancybox image.</li><li><strong>nocaption</strong> : Caption of the image will not be displayed.</li><li><strong>left</strong> : Image will float at the left.</li><li><strong>right</strong> : Image will float at the right.</li><li><strong>center</strong> : Image will be at center.</li><li><strong>fig-20</strong> : Image will take 20% of the width of post width and automatically float at left.</li><li><strong>fig-25</strong> : Image will take 25% of the width of post width and automatically float at left.</li><li><strong>fig-33</strong> : Image will take 33% of the width of post width and automatically float at left.</li><li><strong>fig-50</strong> : Image will take 50% of the width of post width and automatically float at left.</li><li><strong>fig-75</strong> : Image will take 75% of the width of post width and automatically float at left.</li><li><strong>fig-100</strong> : Image will take 100% of the width of post width.</li><li><strong>clear</strong> : Add a div with `clear:both;` style attached after the image to retrieve the normal flow of the post.</li></ul>| |group (optional)| Name of a group, used to create a gallery. **Only for image with `fancybox` css class**| |src| Path to the original image.| @@ -695,7 +695,7 @@ E.g: |thumbnail-width (optional)| Width to the thumbnail image. If the thumbnail image is empty, width will be attached to thumbnail image created from original image. E.g : `150px` or `85%`.| |thumbnail-height (optional)| Height to the thumbnail image. If the thumbnail image is empty, height will be attached to thumbnail image created from original image. E.g : `300px` or `20%`.| |title (optional)| Title of image displayed in a caption under image. `Alt` HTML attribute will use this title. E.g : `"A beautiful sunrise"`.| - + #### Tabbed code block Tabbed code blocks are useful to group multiple code blocks related. For example, the source code of a web component (html, css and js). Or compare a source code in different languages. @@ -713,7 +713,7 @@ Syntax: {{< /tabbed-codeblock >}} ``` -E.g: +E.g: ``` js {{< tabbed-codeblock example http://example.com >}} <!-- tab js --> @@ -725,9 +725,9 @@ E.g: } <!-- endtab --> {{< /tabbed-codeblock >}} -``` +``` |Argument|Description| -|---|---| +|---|---| |Name (optional)|Name of the code block, or of the file| |Link (optional)|Link to a demo, or a file| |Lang (optional)|Programming language use for the current tab| @@ -744,21 +744,21 @@ Syntax: E.g: ``` {{< wide-image src="http://google.fr/images/image125.png" title="A beautiful sunrise" >}} -``` +``` |Argument|Description| -|---|---| +|---|---| |src|Path to the original image.| -|title (optional)|Title of image displayed in a caption under image. `Alt` HTML attribute will use this title. E.g : `"A beautiful sunrise"`.| - +|title (optional)|Title of image displayed in a caption under image. `Alt` HTML attribute will use this title. E.g : `"A beautiful sunrise"`.| + ## Writing pages ## Sometimes you need to create a **page** that is **not** a **regular blog post**, -where you want to hide the date, social sharing buttons, tags, categories +where you want to hide the date, social sharing buttons, tags, categories and pagination. This is the case for the blog pages _About_ or _Contact_ for instance which do -not need to be timestamped (nor tagged or categorized) nor provide +not need to be timestamped (nor tagged or categorized) nor provide pagination and are not intended to be shared on social networks. In order to create such a page you can proceed like so: |