From 5feed2f148f9538076dd836c70a8d3a2db35439a Mon Sep 17 00:00:00 2001 From: Aditya Telange <21258296+adityatelange@users.noreply.github.com> Date: Sun, 7 Feb 2021 21:55:52 +0530 Subject: [PATCH] update docs from wiki --- content/posts/papermod/papermod-faq.md | 33 +--- .../posts/papermod/papermod-features/index.md | 13 +- content/posts/papermod/papermod-icons.md | 118 ++++++------ .../posts/papermod/papermod-installation.md | 15 +- content/posts/papermod/papermod-variables.md | 169 +++++++++--------- 5 files changed, 173 insertions(+), 175 deletions(-) diff --git a/content/posts/papermod/papermod-faq.md b/content/posts/papermod/papermod-faq.md index 4dcdfb2d..217f037c 100644 --- a/content/posts/papermod/papermod-faq.md +++ b/content/posts/papermod/papermod-faq.md @@ -76,33 +76,6 @@ Linked Issues: --- -## Archive Page - -```shell -. -├── config.yml -├── content/ -│ ├── archives.md <--- Create archive.md here -│ └── posts/ -├── static/ -└── themes/ - └── hugo-PaperMod/ -``` - -and add the following to it - -```yml ---- -title: "Archive" -layout: "archives" -url: "/archives/" -summary: archives ---- - -``` - ---- - ## Bundling Custom css with theme's assets - For adding custom css to be bundled inside one minimized css @@ -117,8 +90,8 @@ Create folder in yout project directory as └── assets/ └── css/ └── extended/ <--- - │ ├── custom_css1.css <--- - │ └── any_name.css <--- + ├── custom_css1.css <--- + └── any_name.css <--- ``` All `css` files inside `assets/css/extended` will be bundled ! @@ -303,7 +276,7 @@ Add `#center` after image to center align an image } ``` -More Info : [Configure Markup - Highlight](https://gohugo.io/getting-started/configuration-markup#highlight) + More Info : [Configure Markup - Highlight](https://gohugo.io/getting-started/configuration-markup#highlight) --- diff --git a/content/posts/papermod/papermod-features/index.md b/content/posts/papermod/papermod-features/index.md index 1f496fab..e2f4ee87 100644 --- a/content/posts/papermod/papermod-features/index.md +++ b/content/posts/papermod/papermod-features/index.md @@ -139,6 +139,7 @@ params: profileMode: enabled: true title: "" # optional default will be site title + subtitle: "This is subtitle" imageUrl: "<image link>" # optional imageTitle: "<title of image as alt>" # optional imageWidth: 120 # custom size @@ -158,7 +159,7 @@ params: --- -### Search +### Search Page PaperMod uses [Fuse.js Basic](https://fusejs.io/getting-started/different-builds.html#explanation-of-different-builds) for seach functionality @@ -194,6 +195,12 @@ searchHidden: true ex: [search.md](https://raw.githubusercontent.com/adityatelange/hugo-PaperMod/exampleSite/content/search.md) +> Search Page also has Key bindings: +> +> - Arrow keys to move up/down the list +> - Enter key (return) or Right Arrow key to Go to highlighted page +> - Escape key to clear searchbox and results + For Multilingual use `search.<lang>.md` ex. `search.es.md`. **Note:** Search will work only on current language, user is currently on ! @@ -318,6 +325,8 @@ ShowBreadCrumbs: false ``` +--- + ### Other Posts suggestion below a post Adds a Previous / Next post suggestion under a single post @@ -327,6 +336,8 @@ params: ShowPostNavLinks: true ``` +--- + ### Multiple Authors To Use multiple authors for a post, in post-variables: diff --git a/content/posts/papermod/papermod-icons.md b/content/posts/papermod/papermod-icons.md index 3088e322..18d94b72 100644 --- a/content/posts/papermod/papermod-icons.md +++ b/content/posts/papermod/papermod-icons.md @@ -11,75 +11,75 @@ draft: true ## Social Icons -| No. | Name | Platform Link | -| --- | ------------- | ------------------------------- | -| 1 | 123rf | 123rf.com | -| 2 | adobestock | stock.adobe.com | -| 3 | behance | behance.net | -| 4 | buymeacoffee | buymeacoffee.com | -| 5 | codepen | codepen.io | -| 6 | cryptohack | cryptohack.org | -| 7 | dev | dev.to | -| 8 | discogs | discogs.com | -| 9 | discord | discord.com | -| 10 | dreamstime | dreamstime.com | -| 11 | dribbble | dribbble.com | -| 12 | email | - | -| 13 | facebook | facebook.com | -| 14 | freepik | freepik.com | -| 15 | github | github.com | -| 16 | gitlab | gitlab.com | -| 17 | hackerrank | hackerrank.com | -| 18 | hackthebox | hackthebox.eu | -| 19 | instagram | instagram.com | -| 20 | kakaotalk | kakaocorp.com/service/KakaoTalk | -| 21 | keybase | keybase.io | -| 22 | kofi | ko-fi.com | -| 23 | lastfm | last.fm | -| 24 | linkedin | linkedin.com | -| 25 | mastodon | mastodon.social | -| 26 | medium | medium.com | -| 27 | mixcloud | mixcloud.com | -| 28 | nuget | nuget.org | -| 29 | paypal | paypal.com | -| 30 | qq | qq.com | -| 31 | reddit | reddit.com | -| 32 | rss | - | -| 33 | soundcloud | soundcloud.com | -| 34 | shutterstock | shutterstock.com | -| 35 | slack | slack.com | -| 36 | snapchat | snapchat.com/add | -| 37 | sourcerer | sourcerer.io | -| 38 | stackoverflow | stackoverflow.com | -| 39 | steam | steampowered.com | -| 40 | telegram | telegram.org | -| 41 | twitch | twitch.tv | -| 42 | twitter | twitter.com | -| 43 | youtube | youtube.com | -| 44 | other | - | +| No. | Name | Platform Link | +| --- | --------------- | ------------------------------- | +| 1 | `123rf` | 123rf.com | +| 2 | `adobestock` | stock.adobe.com | +| 3 | `behance` | behance.net | +| 4 | `buymeacoffee` | buymeacoffee.com | +| 5 | `codepen` | codepen.io | +| 6 | `cryptohack` | cryptohack.org | +| 7 | `dev` | dev.to | +| 8 | `discogs` | discogs.com | +| 9 | `discord` | discord.com | +| 10 | `dreamstime` | dreamstime.com | +| 11 | `dribbble` | dribbble.com | +| 12 | `email` | - | +| 13 | `facebook` | facebook.com | +| 14 | `freepik` | freepik.com | +| 15 | `github` | github.com | +| 16 | `gitlab` | gitlab.com | +| 17 | `hackerrank` | hackerrank.com | +| 18 | `hackthebox` | hackthebox.eu | +| 19 | `instagram` | instagram.com | +| 20 | `kakaotalk` | kakaocorp.com/service/KakaoTalk | +| 21 | `keybase` | keybase.io | +| 22 | `kofi` | ko-fi.com | +| 23 | `lastfm` | last.fm | +| 24 | `linkedin` | linkedin.com | +| 25 | `mastodon` | mastodon.social | +| 26 | `medium` | medium.com | +| 27 | `mixcloud` | mixcloud.com | +| 28 | `nuget` | nuget.org | +| 29 | `paypal` | paypal.com | +| 30 | `qq` | qq.com | +| 31 | `reddit` | reddit.com | +| 32 | `rss` | - | +| 33 | `soundcloud` | soundcloud.com | +| 34 | `shutterstock` | shutterstock.com | +| 35 | `slack` | slack.com | +| 36 | `snapchat` | snapchat.com/add | +| 37 | `sourcerer` | sourcerer.io | +| 38 | `stackoverflow` | stackoverflow.com | +| 39 | `steam` | steampowered.com | +| 40 | `telegram` | telegram.org | +| 41 | `twitch` | twitch.tv | +| 42 | `twitter` | twitter.com | +| 43 | `youtube` | youtube.com | +| 44 | `other` | - | Usage : ``` -socialIcons: # optional - - name: "<NAME>" - url: "<link>" - - name: "<NAME>" - url: "<link2>" +socialIcons: + - name: "kofi" + url: "https://kofi.com" + - name: "twitter" + url: "https://twitter.com" ``` --- ## Share Icons -| No. | Platform | -| --- | -------- | -| 1 | twitter | -| 2 | linkedin | -| 3 | reddit | -| 4 | facebook | -| 5 | whatsapp | -| 6 | telegram | +| No. | Platform | +| --- | --------------------------------------------------------------- | +| 1 | `twitter` (also generates hash tags from tags linked with post) | +| 2 | `linkedin` | +| 3 | `reddit` | +| 4 | `facebook` | +| 5 | `whatsapp` | +| 6 | `telegram` | Usage: diff --git a/content/posts/papermod/papermod-installation.md b/content/posts/papermod/papermod-installation.md index c8a710b8..7107de8c 100644 --- a/content/posts/papermod/papermod-installation.md +++ b/content/posts/papermod/papermod-installation.md @@ -9,9 +9,21 @@ tags: ["PaperMod"] author: "Aditya Telange" --- + +## Intro + +- **We'll be using `yml/yaml` format for all examples down below, I recommend using `yml` over `toml` as it is easier to read.** +- You can find any [YML to TOML](https://www.google.com/search?q=yml+to+toml) converters if necessary. + +--- ## Guide Follow [Quick Start](https://gohugo.io/getting-started/quick-start/) guide to setup hugo and create a new site. + +> Note: Use -f to select yml format +> +> `hugo new site <name of site> -f yml` + Make sure you install latest version of **`hugo(>=0.74.0)`**. After you have created a new site, at [Step 3](https://gohugo.io/getting-started/quick-start/#step-3-add-a-theme) follow the steps: @@ -39,7 +51,7 @@ you can use as [submodule](https://www.atlassian.com/git/tutorials/git-submodule ```bash git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod --depth=1 -git submodule update --init --recursive +git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically) ``` **Note**: You may use ` --branch v4.0` to end of above command if you want to stick to specific release. @@ -146,6 +158,7 @@ params: profileMode: enabled: false # needs to be explicitly set title: ExampleSite + subtitle: "This is subtitle" imageUrl: "<img location>" imageWidth: 120 imageHeight: 120 diff --git a/content/posts/papermod/papermod-variables.md b/content/posts/papermod/papermod-variables.md index 36c959eb..8a7c79b1 100644 --- a/content/posts/papermod/papermod-variables.md +++ b/content/posts/papermod/papermod-variables.md @@ -14,75 +14,88 @@ weight: 5 ### Site Variables under `Params` -| name | type | example | Description | -| ------------------------------------ | ------------- | ------------------------ | ----------------------------------------------------------------------------------- | -| env | string | 'production' | To set env to production | -| title | string | 'My Blog' | To set title | -| description | string | 'This is a blog of mine' | To set site description | -| author | string \|list | 'Me' \| ['Me','You'] | To show multiple Authors | -| images | string | 'myimage.png' | Link or path of image for opengraph, twitter-cards | -| ShowReadingTime | boolean | true \| false | To show read time in post meta | -| ShowShareButtons | boolean | true \| false | To show/hide share buttons under post | -| defaultTheme | string | light \| dark \| auto | To set default theme | -| disableThemeToggle | boolean | true \| false | To disable theme toggle icon shown besides label | -| disableSpecial1stPost | boolean | true \| false | To disable no-card special appearance of 1st post | -| hidemeta | boolean | true \| false | To Hide meta elements : date, read-time, author and available-translations for page | -| showtoc | boolean | true \| false | To show/hide Table of Contents | -| tocopen | boolean | true \| false | To keep open ToC by default on page load | -| ShowPostNavLinks | boolean | true \| false | Show Previous and Next Posts below a Post | -| ShowBreadCrumbs | boolean | true \| false | Show BreadCrumb Navigation above single post/page | -| comments | boolean | true \| false | To show/hide comments | -| analytics.google.SiteVerificationTag | string | "XYZabc" | Site Verification Tag for Google Analytics | -| analytics.bing.SiteVerificationTag | string | "XYZabc" | Site Verification Tag for Bing | -| analytics.yandex.SiteVerificationTag | string | "XYZabc" | Site Verification Tag for Yandex | -| | | | | -| fuseOpts | - | - | [Details](#fuseOpts) | -| socialIcons | - | - | [Details](#socialIcons) | -| label | - | - | [Details](#label) | -| assets | - | - | [Details](#assets) | -| cover | - | - | [Details](#cover) | -| profileMode | - | - | [Details](#profilemode) | +| name | type | example | Description | +| -------------------------------------- | ------------- | ------------------------ | ----------------------------------------------------------------------------------- | +| `env` | string | 'production' | To set env to production | +| `title` | string | 'My Blog' | To set title | +| `description` | string | 'This is a blog of mine' | To set site description | +| `author` | string \|list | 'Me' \| ['Me','You'] | To show multiple Authors | +| `images` | string | 'myimage.png' | Link or path of image for opengraph, twitter-cards | +| `ShowReadingTime` | boolean | true \| false | To show read time in post meta | +| `ShowShareButtons` | boolean | true \| false | To show/hide share buttons under post | +| `defaultTheme` | string | light \| dark \| auto | To set default theme | +| `disableThemeToggle` | boolean | true \| false | To disable theme toggle icon shown besides label | +| `disableSpecial1stPost` | boolean | true \| false | To disable no-card special appearance of 1st post | +| `hidemeta` | boolean | true \| false | To Hide meta elements : date, read-time, author and available-translations for page | +| `showtoc` | boolean | true \| false | To show/hide Table of Contents | +| `tocopen` | boolean | true \| false | To keep open ToC by default on page load | +| `ShowPostNavLinks` | boolean | true \| false | Show Previous and Next Posts below a Post | +| `ShowBreadCrumbs` | boolean | true \| false | Show BreadCrumb Navigation above single post/page | +| `comments` | boolean | true \| false | To show/hide comments | +| `analytics.google.SiteVerificationTag` | string | "XYZabc" | Site Verification Tag for Google Analytics | +| `analytics.bing.SiteVerificationTag` | string | "XYZabc" | Site Verification Tag for Bing | +| `analytics.yandex.SiteVerificationTag` | string | "XYZabc" | Site Verification Tag for Yandex | +| `fuseOpts` | - | - | [Details](#fuseOpts) | +| `socialIcons` | - | - | [Details](#socialIcons) | +| `label` | - | - | [Details](#label) | +| `assets` | - | - | [Details](#assets) | +| `cover` | - | - | [Details](#cover) | +| `profileMode` | - | - | [Details](#profilemode) | #### label -| name | type | example | Description | -| ---------------- | ------- | ----------------------- | ------------------------------------------------ | -| label.text | string | 'Home' | To display different label text other than title | -| label.icon | string | '/apple-touch-icon.png' | To display a logo image in label | -| label.iconHeight | integer | 35 | To set size of label logo image | +| name | type | example | Description | +| ------------------ | ------- | ----------------------- | ------------------------------------------------ | +| `label.text` | string | 'Home' | To display different label text other than title | +| `label.icon` | string | '/apple-touch-icon.png' | To display a logo image in label | +| `label.iconHeight` | integer | 35 | To set size of label logo image | #### profileMode -| name | type | example | Description | -| ----------------------- | ------- | ---------------------------------------------- | ----------- | -| profileMode.enabled | boolean | true \| false | | -| profileMode.title | string | "Title" | | -| profileMode.imageUrl | string | "image.png" \| "https://example.com/image.jpg" | | -| profileMode.imageWidth | string | "" | | -| profileMode.imageHeight | string | "" | | -| profileMode.imageTitle | string | "This image is a picture of .." | | -| profileMode.buttons | - | - | | +| name | type | example | Description | +| ------------------------- | ------- | ---------------------------------------------- | ---------------------------------------------------- | +| `profileMode.enabled` | boolean | true \| false | For enabling profileMode, needs to be explicitly set | +| `profileMode.title` | string | "Title" | Title | +| `profileMode.subtitle` | string | "subtitle here" | Subtitle | +| `profileMode.imageUrl` | string | "image.png" \| "https://example.com/image.jpg" | Image URL or Link | +| `profileMode.imageWidth ` | string | "150" | Width of image | +| `profileMode.imageHeight` | string | "150" | Height of image | +| `profileMode.imageTitle` | string | "This image is a picture of .." | Title of image | +| `profileMode.buttons` | - | - | [Details](#profileModebuttons) | + +##### profileMode.buttons + +```yml +profileMode: + buttons: + - name: Archive + url: "/archive" + - name: Github + url: "https://github.com/" +``` #### assets -| name | type | example | Description | -| ---------------------------- | ------- | ---------- | -------------------------------------------- | -| assets.favicon | string | 'icon.ico' | To set favicon, can be path or external link | -| assets.disableHLJS | boolean | | | -| assets.disableFingerprinting | boolean | | | +| name | type | example | Description | +| ------------------------------ | ------- | ------------- | -------------------------------------------- | +| `assets.favicon` | string | 'icon.ico' | To set favicon, can be path or external link | +| `assets.disableHLJS` | boolean | true \| false | To disable Highlight.js loading | +| `assets.disableFingerprinting` | boolean | true \| false | To disable Sub-Resource integrity for assets | #### cover -| name | type | example | Description | -| ---------------------- | ------- | ------------- | ------------------------------------------------------- | -| cover.linkFullImages | boolean | true \| false | To open full size cover images on click on cover | -| cover.responsiveImages | boolean | true \| false | To enable/disable generation of responsive cover images | -| cover.hidden | boolean | true \| fals | | -| cover.hiddenInList | boolean | true \| fals | | -| cover.hiddenInSingle | boolean | true \| fals | | +| name | type | example | Description | +| ------------------------ | ------- | ------------- | ------------------------------------------------------- | +| `cover.linkFullImages` | boolean | true \| false | To open full size cover images on click on cover | +| `cover.responsiveImages` | boolean | true \| false | To enable/disable generation of responsive cover images | +| `cover.hidden` | boolean | true \| false | To hide everywhere but not in structured data | +| `cover.hiddenInList` | boolean | true \| false | To hide on list pages and home | +| `cover.hiddenInSingle ` | boolean | true \| false | To hide on list pages and home | #### fuseOpts +Refer: https://fusejs.io/api/options.html + ```yml fuseOpts: isCaseSensitive: false @@ -104,37 +117,25 @@ socialIcons: url: "<link2>" ``` -#### - -```yml -profileMode: - buttons: - - name: Archive - url: "/archive" - - name: Github - url: "https://github.com/" -``` - --- ### Page Variables -| Name | Type | Example | Description | -| --------------- | ------------- | --------------------- | ----------------------------------------------------------------------------------- | -| showtoc | boolean | true \| false | To show/hide Table of Contents | -| tocopen | boolean | true \| false | To keep open ToC by default on page load | -| hidemeta | boolean | true \| false | To Hide meta elements : date, read-time, author and available-translations for page | -| comments | boolean | true \| false | To show/hide comments | -| description | string | 'description text' | Show Post Description under Title | -| disableShare | boolean | true \| false | To hide/show share icons under a page | -| disableHLJS | boolean | true \| false | | -| searchHidden | boolean | true \| false | | -| ShowBreadCrumbs | boolean | true \| false | Show BreadCrumb Navigation above single post/page | -| author | string \|list | 'Me' \| ['Me','You'] | To show multiple Authors | -| cover.image | string | 'featured.jpg' | To add a cover image | -| cover.caption | string | 'caption for image' | To add caption to cover image | -| cover.alt | string | 'this is cover image' | Alternate text to show if image doesn't load/show up | -| cover.relative | boolean | true \| false | To use relative path for cover image, used in hugo Page-bundles | -| cover.hidden | boolean | true \| false | | -| | | | | -| weight | integer | 5 | To set page order or to pin a post to Top of list | +| Name | Type | Example | Description | +| ----------------- | ------------- | --------------------- | ----------------------------------------------------------------------------------- | +| `showtoc` | boolean | true \| false | To show/hide Table of Contents | +| `tocopen` | boolean | true \| false | To keep open ToC by default on page load | +| `hidemeta` | boolean | true \| false | To Hide meta elements : date, read-time, author and available-translations for page | +| `comments` | boolean | true \| false | To show/hide comments | +| `description` | string | 'description text' | Show Post Description under Title | +| `disableShare` | boolean | true \| false | To hide/show share icons under a page | +| `disableHLJS` | boolean | true \| false | To disable Highlight.js loading | +| `searchHidden` | boolean | true \| false | Hide page from search | +| `ShowBreadCrumbs` | boolean | true \| false | Show BreadCrumb Navigation above single post/page | +| `author` | string \|list | 'Me' \| ['Me','You'] | To show multiple Authors | +| `cover.image` | string | 'featured.jpg' | To add a cover image | +| `cover.caption ` | string | 'caption for image' | To add caption to cover image | +| `cover.alt` | string | 'this is cover image' | Alternate text to show if image doesn't load/show up | +| `cover.relative` | boolean | true \| false | To use relative path for cover image, used in hugo Page-bundles | +| `cover.hidden ` | boolean | true \| false | To hide on current single page | +| `weight ` | integer | 5 | To set page order or to pin a post to Top of list |