From 859826c05237718ae1c2cdd924b0f7f670f00ef0 Mon Sep 17 00:00:00 2001 From: Aditya Telange <21258296+adityatelange@users.noreply.github.com> Date: Fri, 26 Jan 2024 13:07:49 +0530 Subject: [PATCH] ync wiki with examplesite docs --- FAQs.md | 83 ++++++------- Features.md | 302 +++++++++++++++++++++++++++--------------------- Home.md | 17 ++- Icons.md | 29 +++-- Installation.md | 230 +++++++++++++++++++++--------------- Variables.md | 17 ++- 6 files changed, 368 insertions(+), 310 deletions(-) diff --git a/FAQs.md b/FAQs.md index eaf739a..299f864 100644 --- a/FAQs.md +++ b/FAQs.md @@ -1,6 +1,5 @@ ## ToC -- [Intro](#intro) - [Override theme template](#override-theme-template) - [Enable Social-Metadata and SEO](#enable-social-metadata-and-seo) - [Failed to find a valid digest in the 'integrity' attribute for resource ... ?](#failed-to-find-a-valid-digest-in-the-integrity-attribute-for-resource--) @@ -12,15 +11,14 @@ - [Centering image in markdown](#centering-image-in-markdown) - [Using Hugo's Syntax highlighter "chroma"](#using-hugos-syntax-highlighter-chroma) - [Posts from only one folder/section visible on home page?](#posts-from-only-one-foldersection-visible-on-home-page) +- [Search not working ?](#search-not-working-) - [References](#references) --- -## 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. +> - **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. --- @@ -49,7 +47,7 @@ When Hugo builds your site, your copy of `list.html` will be used instead of the These include OpenGraph, Twitter Cards and Schema. -```yml +```yml {linenos=true} params: env: production ``` @@ -68,7 +66,7 @@ Why was the `asset` not loading ? : [How_browsers_handle_Subresource_Integrity]( Set the following in `config.yml` -```yml +```yml {linenos=true} params: assets: disableFingerprinting: true @@ -141,7 +139,7 @@ You can add menu entries which will appear in the header of every page. To do so, add a `menu` section to your site's `config.yml`: -```yml +```yml {linenos=true} menu: main: - identifier: categories @@ -172,7 +170,7 @@ Post can be pinned/ displayed top on the list by adding a `weight=` var to example: -```yml +```yml {linenos=true} --- title: "My Important post" date: 2020-09-15T11:30:03+00:00 @@ -180,7 +178,7 @@ weight: 1 --- ``` -```yml +```yml {linenos=true} --- title: "My 2nd Important post" date: 2020-09-15T11:30:03+00:00 @@ -201,37 +199,33 @@ and can be added accordingly. - `apple-touch-icon.png` - `safari-pinned-tab.svg` -1. Favicon(s) can be generated by [Favicon.io](https://favicon.io) - - and can be simply put in `/static` folder. +1. Favicon(s) can be generated by [Favicon.io](https://favicon.io) and can be simply put in `/static` folder. 2. Other way is to add favicon(s) NOT located in `/static` folder. In site config add the following: - ``` + ```yml {linenos=true} params: assets: favicon: "" - favicon16x16: "" - favicon32x32: "" - apple_touch_icon: "" - safari_pinned_tab: "" + favicon16x16: "" + favicon32x32: "" + apple_touch_icon: "" + safari_pinned_tab: "" ``` - - `absolute url` means direct links to external resource: ex. https://web.site/someimage.png + Note: `absolute url` means direct links to external resource: ex. `https://web.site/someimage.png` - example: - - ``` - params: - assets: - favicon: "/favicon.ico" - favicon16x16: "/favicon-16x16.png" - favicon32x32: "/favicon-32x32.png" - apple_touch_icon: "/apple-touch-icon.png" - safari_pinned_tab: "/safari-pinned-tab.svg" - ``` +```yml {linenos=true} +params: + assets: + favicon: "/favicon.ico" + favicon16x16: "/favicon-16x16.png" + favicon32x32: "/favicon-32x32.png" + apple_touch_icon: "/apple-touch-icon.png" + safari_pinned_tab: "/safari-pinned-tab.svg" +``` --- @@ -239,7 +233,7 @@ and can be added accordingly. Add `#center` after image to center align an image -```md +```md {linenos=true} ![name](path/to/image.png#center) ``` @@ -247,10 +241,8 @@ Add `#center` after image to center align an image use `align=center` to center image with captions -ex. - -```md -{{< figure align=center src="image.jpg" >}} +```md {linenos=true} +{{}} ``` --- @@ -259,7 +251,7 @@ ex. 1. Disable Highlight.js in site `config.yml` - ```yml + ```yml {linenos=true} params: assets: disableHLJS: true @@ -267,7 +259,7 @@ ex. 2. Set hugo's markdown styling in site `config.yml` - ```yml + ```yml {linenos=true} markup: highlight: # anchorLineNos: true @@ -284,16 +276,11 @@ ex. Add the following to `assets/css/extended/custom.css` - ```css + ```css {linenos=true} .chroma { - background-color: unset !important; + background-color: unset; } ``` - - You can use, for ex. - ```sh - hugo gen chromastyles --style dracula > assets/css/extended/dracula.css - ``` More Info : [Configure Markup - Highlight](https://gohugo.io/getting-started/configuration-markup#highlight) @@ -311,7 +298,7 @@ We have used this insted of assigning `baseURL` so as to work with multilingual To fix for _single_ language websites hosting assets from CDN, this you may [override](#override-theme-template) [fastsearch.js#L35](https://github.com/adityatelange/hugo-PaperMod/blob/fb4988cfb6d0d6e4e489f17d89f0fa618def3396/assets/js/fastsearch.js#L35) and placing appropriate URL as in -```js +```js {linenos=true} xhr.open("GET", "https://example.com/index.json"); ``` @@ -328,8 +315,8 @@ You can customize it with: ```yml params: mainSections: - - blog - - docs + - blog + - docs ``` --- diff --git a/Features.md b/Features.md index a6382e5..8841ed5 100644 --- a/Features.md +++ b/Features.md @@ -1,44 +1,44 @@ ## ToC -- [Assets (js/css)](#assets-jscss) -- [Default Theme light/dark/auto](#default-theme-lightdarkauto) -- [Theme Switch Toggle (enabled by default)](#theme-switch-toggle-enabled-by-default) -- [Archives Layout](#archives-layout) -- [Regular Mode (default-mode)](#regular-mode-default-mode) -- [Home-Info Mode](#home-info-mode) -- [Profile Mode](#profile-mode) -- [Search Page](#search-page) -- [Draft Page indication](#draft-page-indication) -- [Post Cover Image](#post-cover-image) -- [Share Buttons on post](#share-buttons-on-post) -- [Show post reading time](#show-post-reading-time) -- [Show Table of Contents (Toc) on blog post](#show-table-of-contents-toc-on-blog-post) -- [BreadCrumb Navigation](#breadcrumb-navigation) -- [Edit Link for Posts](#edit-link-for-posts) -- [Other Posts suggestion below a post](#other-posts-suggestion-below-a-post) -- [Code Copy Button](#code-copy-button) -- [Multiple Authors](#multiple-authors) -- [Comments](#comments) -- [AccessKeys](#accesskeys) -- [Enhanced SEO](#enhanced-seo) -- [Multilingual Support](#multilingual-support) -- [Misc](#misc) - - [Scroll-Bar themed (by default)](#scroll-bar-themed-by-default) - - [Smooth Scroll between in-page links (by default)](#smooth-scroll-between-in-page-links-by-default) - - [Scroll-to-Top Button (by default)](#scroll-to-top-button-by-default) - - [Google Analytics integration](#google-analytics-integration) - - [Syntax highlighting](#syntax-highlighting) - - [RSS feeds](#rss-feeds) +- [Assets (js/css)](#assets-jscss) +- [Default Theme light/dark/auto](#default-theme-lightdarkauto) +- [Theme Switch Toggle (enabled by default)](#theme-switch-toggle-enabled-by-default) +- [Archives Layout](#archives-layout) +- [Regular Mode (default-mode)](#regular-mode-default-mode) +- [Home-Info Mode](#home-info-mode) +- [Profile Mode](#profile-mode) +- [Search Page](#search-page) +- [Draft Page indication](#draft-page-indication) +- [Post Cover Image](#post-cover-image) +- [Share Buttons on post](#share-buttons-on-post) +- [Show post reading time](#show-post-reading-time) +- [Show Table of Contents (Toc) on blog post](#show-table-of-contents-toc-on-blog-post) +- [BreadCrumb Navigation](#breadcrumb-navigation) +- [Edit Link for Posts](#edit-link-for-posts) +- [Other Posts suggestion below a post](#other-posts-suggestion-below-a-post) +- [Code Copy Button](#code-copy-button) +- [Multiple Authors](#multiple-authors) +- [Comments](#comments) +- [AccessKeys](#accesskeys) +- [Enhanced SEO](#enhanced-seo) + - [Twitter Cards Support](#twitter-cards-support) + - [OpenGraph support](#opengraph-support) +- [Multilingual Support](#multilingual-support) +- [Misc](#misc) + - [Scroll-Bar themed (by default)](#scroll-bar-themed-by-default) + - [Smooth Scroll between in-page links (by default)](#smooth-scroll-between-in-page-links-by-default) + - [Scroll-to-Top Button (by default)](#scroll-to-top-button-by-default) + - [Google Analytics integration](#google-analytics-integration) + - [Syntax highlighting](#syntax-highlighting) + - [RSS feeds](#rss-feeds) View demo [here](https://adityatelange.github.io/hugo-PaperMod/) --- -## 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. +> - **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. --- @@ -46,19 +46,19 @@ View demo [here](https://adityatelange.github.io/hugo-PaperMod/) The following is enabled by default -- [minification](https://gohugo.io/hugo-pipes/minification/) - makes the assets size smallest as possible. -- [bundling](https://gohugo.io/hugo-pipes/bundling/) - bundles all the styles in one single asset -- [fingerprint/intergity](https://gohugo.io/hugo-pipes/fingerprint/) check. +- [minification](https://gohugo.io/hugo-pipes/minification/) - makes the assets size smallest as possible. +- [bundling](https://gohugo.io/hugo-pipes/bundling/) - bundles all the styles in one single asset +- [fingerprint/intergity](https://gohugo.io/hugo-pipes/fingerprint/) check. --- ### Default Theme light/dark/auto -```yml +```yml {linenos=true} params: - # defaultTheme: light - # defaultTheme: dark - defaultTheme: auto # to switch between dark or light according to browser theme + # defaultTheme: light + # defaultTheme: dark + defaultTheme: auto # to switch between dark or light according to browser theme ``` @@ -71,7 +71,7 @@ Shows icon besides title of page to change theme To disable it : -```yml +```yml {linenos=true} disableThemeToggle: true ``` @@ -112,7 +112,6 @@ layout: "archives" url: "/archives/" summary: archives --- - ``` **Note:** Archives Layout does not support Multilingual Month Translations. @@ -137,15 +136,15 @@ add following to config file ```yml params: - homeInfoParams: - Title: Hi there wave - Content: Can be Info, links, about... + homeInfoParams: + Title: Hi there wave + Content: Can be Info, links, about... - socialIcons: # optional - - name: "" - url: "" - - name: "" - url: "" + socialIcons: # optional + - name: "" + url: "" + - name: "" + url: "" ``` --- @@ -158,63 +157,61 @@ Shows Index/Home page as Full Page with Social Links and Image add following to config file -```yml +```yml {linenos=true} 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 - imageHeight: 120 # custom size - buttons: - - name: Archive - url: "/archive" - - name: Github - url: "https://github.com/" + profileMode: + enabled: true + title: "<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 + imageHeight: 120 # custom size + buttons: + - name: Archive + url: "/archive" + - name: Github + url: "https://github.com/" - socialIcons: # optional - - name: "<platform>" - url: "<link>" - - name: "<platform 2>" - url: "<link2>" + socialIcons: # optional + - name: "<platform>" + url: "<link>" + - name: "<platform 2>" + url: "<link2>" ``` --- ### Search Page -PaperMod uses [Fuse.js Basic](https://fusejs.io/getting-started/different-builds.html#explanation-of-different-builds) for seach functionality +PaperMod uses [Fuse.js Basic](https://fusejs.io/getting-started/different-builds.html#explanation-of-different-builds) for search functionality Add the following to site config, `config.yml` -```yml +```yml {linenos=true,hl_lines=[5]} outputs: - home: - - HTML - - RSS - - JSON # is necessary + home: + - HTML + - RSS + - JSON # necessary for search ``` Create a page with `search.md` in `content` directory with following content -```yml +```yml {linenos=true,hl_lines=[3]} --- title: "Search" # in any language you want -layout: "search" # is necessary +layout: "search" # necessary for search # url: "/archive" # description: "Description for Search" summary: "search" placeholder: "placeholder text in search input box" --- - ``` -To hide a particular page from being searched, add it in post's fron't matter +To hide a particular page from being searched, add it in post's frontmatter -```yml ---- +```yml {linenos=true} searchHidden: true ``` @@ -222,9 +219,9 @@ ex: [search.md](https://raw.githubusercontent.com/adityatelange/hugo-PaperMod/ex > 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 +> - Arrow keys to move up/down the list +> - Enter key (return) or Right Arrow key to go to the highlighted page +> - Escape key to clear searchbox and results For Multilingual use `search.<lang>.md` ex. `search.es.md`. @@ -234,16 +231,17 @@ For Multilingual use `search.<lang>.md` ex. `search.es.md`. Refer https://fusejs.io/api/options.html for Options, Add those as shown below. -```yml +```yml {linenos=true} params: - fuseOpts: - isCaseSensitive: false - shouldSort: true - location: 0 - distance: 1000 - threshold: 0.4 - minMatchCharLength: 0 - keys: ["title", "permalink", "summary", "content"] + fuseOpts: + isCaseSensitive: false + shouldSort: true + location: 0 + distance: 1000 + threshold: 0.4 + minMatchCharLength: 0 + # limit: 10 # refer: https://www.fusejs.io/api/methods.html#search + keys: ["title", "permalink", "summary", "content"] ``` --- @@ -258,32 +256,32 @@ adds `[draft]` mark to indicate draft pages. In post's page-variables add : -```yml +```yml {linenos=true} cover: - image: "<image path/url>" - # can also paste direct link from external site - # ex. https://i.ibb.co/K0HVPBd/paper-mod-profilemode.png - alt: "<alt text>" - caption: "<text>" - relative: false # To use relative path for cover image, used in hugo Page-bundles + image: "<image path/url>" + # can also paste direct link from external site + # ex. https://i.ibb.co/K0HVPBd/paper-mod-profilemode.png + alt: "<alt text>" + caption: "<text>" + relative: false # To use relative path for cover image, used in hugo Page-bundles ``` When you include images in the [Page Bundle](https://gohugo.io/content-management/page-bundles/), multiple sizes of the image will automatically be provided using the HTML5 `srcset` field. To reduce generation time and size of the site, you can disable this feature using -```yml +```yml {linenos=true} params: - cover: - responsiveImages: false + cover: + responsiveImages: false ``` To enable hyperlinks to the full image size on post pages, use -```yml +```yml {linenos=true} params: - cover: - linkFullImages: true + cover: + linkFullImages: true ``` --- @@ -296,7 +294,7 @@ to show share buttons add ```yml params: - ShowShareButtons: true + ShowShareButtons: true ``` --- @@ -309,7 +307,7 @@ To show reading time add ```yml Params: - ShowReadingTime: true + ShowReadingTime: true ``` --- @@ -338,16 +336,15 @@ Adds BreadCrumb Navigation above Post's Title to show subsections and Navigation ```yml params: - ShowBreadCrumbs: true + ShowBreadCrumbs: true ``` -Can be disabled for particular page's front-matter +Can be diabled for particular page's front-matter ```yml --- ShowBreadCrumbs: false --- - ``` --- @@ -360,10 +357,10 @@ For site config use: ```yml Params: - editPost: - URL: "https://github.com/<gitlab user>/<repo name>/tree/<branch name>/<path to content>/" - Text: "Suggest Changes" # edit text - appendFilePath: true # to append file path to Edit link + editPost: + URL: "https://github.com/<path_to_repo>/content" + Text: "Suggest Changes" # edit text + appendFilePath: true # to append file path to Edit link ``` Can be modified for individual pages @@ -371,21 +368,20 @@ Can be modified for individual pages ```yml --- editPost: - URL: "https://github.com/<path_to_repo>/content" - Text: "Suggest Changes" # edit text - appendFilePath: true # to append file path to Edit link + URL: "https://github.com/<path_to_repo>/content" + Text: "Suggest Changes" # edit text + appendFilePath: true # to append file path to Edit link --- - ``` The example above would yield the following link for the post file `posts/post-name.md`: -https://github.com/<path_to_repo>/content/posts/post-name.md +`https://github.com/<path_to_repo>/content/posts/post-name.md` -| Parameter | Required | Default Value | -| ----------------------- | -------- | ------------- | -| editPost.URL | true | - | -| editPost.appendFilePath | false | false | -| editPost.Text | false | "Edit" | +| Parameter | Required | Default Value | +| ------------------------- | -------- | ------------- | +| `editPost.URL` | true | - | +| `editPost.appendFilePath` | false | `false` | +| `editPost.Text` | false | `Edit` | Since the link generated is a regular HTML anchor tag `<a href=...>`, you can also use other URL schemas like `mailto://`, e.g. @@ -399,7 +395,7 @@ Adds a Previous / Next post suggestion under a single post ```yml params: - ShowPostNavLinks: true + ShowPostNavLinks: true ``` --- @@ -410,7 +406,7 @@ Adds a `copy` button in code block to copy the code it contains ```yml params: - ShowCodeCopyButtons: true + ShowCodeCopyButtons: true ``` --- @@ -423,14 +419,13 @@ To Use multiple authors for a post, in post-variables: --- author: ["Me", "You"] --- - ``` To use Multiple Authors Site-wide, in `config.yml`: ```yml params: - author: ["Me", "You"] + author: ["Me", "You"] ``` --- @@ -447,7 +442,7 @@ also in config add this ```yml params: - comments: true + comments: true ``` read more about this [hugo-comments](https://gohugo.io/content-management/comments/) @@ -472,11 +467,50 @@ t - Theme toggle **Enabled only when `env: production`** -- [Rich Results/Snippets Support](https://support.google.com/webmasters/answer/7506797?hl=en) +- [Rich Results/Snippets Support](https://support.google.com/webmasters/answer/7506797?hl=en) -- Twitter Cards Support +#### Twitter Cards Support -- Open-Graph support +- The Twitter Cards metadata, except `twitter:image` should not require + additional configuration, since it is generated from metadata that + you should already have (for instance the page title and description). +- The `twitter:image` uses the [Post Cover Image](#post-cover-image), if present. +- In the absence of a cover images, the first image from the `images` + frontmatter (a list) is used. + ```yaml + images: + - image_01.png + - image_02.png + ``` +- Finally, if neither of those are provided, `twitter:image` comes from the first + [Page Bundle](https://gohugo.io/content-management/page-bundles/) + image with `feature` in the name, with a fallback to the first image with + `cover` or `thumbnail` in the name. + +#### OpenGraph support + +- The OpenGraph metadata, except `og:image` should not require + additional configuration, since it is generated from metadata that + you should already have (for instance the page title and description). +- The `og:image` uses the [Post Cover Image](#post-cover-image), if present. +- In the absence of a cover images, the first image from the `images` + frontmatter (a list) is used. + ```yaml + images: + - image_01.png + - image_02.png + ``` +- Finally, if neither of those are provided, `og:image` comes from the first + [Page Bundle](https://gohugo.io/content-management/page-bundles/) + image with `feature` in the name, with a fallback to the first image with + `cover` or `thumbnail` in the name. +- For pages, you can also add audio (using frontmatter `audio: filename.ext`) and/or + videos. + ```yaml + videos: + - filename01.mov + - filename02.avi + ``` --- diff --git a/Home.md b/Home.md index 79dfb4e..f6e4ccb 100644 --- a/Home.md +++ b/Home.md @@ -1,7 +1,6 @@ # Welcome to the PaperMod's wiki! -Hugo PaperMod is a theme based on [hugo-paper](https://github.com/nanxiaobei/hugo-paper). -The goal of this project is add more Features and customization to the og theme. +> Hugo PaperMod is a theme based on [hugo-paper](https://github.com/nanxiaobei/hugo-paper). The [demo site](https://adityatelange.github.io/hugo-PaperMod/) includes a lot of documentation about Installation, Features with few more stuff. Make sure you visit it, to get the awesome hands-on experience and get known about the features ... @@ -15,16 +14,16 @@ ExampleSite can be found here: [exampleSite](https://github.com/adityatelange/hu ## Quick Links -- ### [Install / Update](https://github.com/adityatelange/hugo-PaperMod/wiki/Installation) +- [Install / Update](https://github.com/adityatelange/hugo-PaperMod/wiki/Installation) -- ### [Features](https://github.com/adityatelange/hugo-PaperMod/wiki/Features) +- [Features](https://github.com/adityatelange/hugo-PaperMod/wiki/Features) -- ### [Icons](https://github.com/adityatelange/hugo-PaperMod/wiki/Icons) +- [Icons](https://github.com/adityatelange/hugo-PaperMod/wiki/Icons) -- ### [FAQs](https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs) +- [FAQs](https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs) -- ### [Variables](https://github.com/adityatelange/hugo-PaperMod/wiki/Variables) +- [Variables](https://github.com/adityatelange/hugo-PaperMod/wiki/Variables) -- ### [Translations](https://github.com/adityatelange/hugo-PaperMod/wiki/Translations) +- [Translations](https://github.com/adityatelange/hugo-PaperMod/wiki/Translations) -- ### [ChangeLog](https://github.com/adityatelange/hugo-PaperMod/wiki/ChangeLog) +- [ChangeLog](https://github.com/adityatelange/hugo-PaperMod/wiki/ChangeLog) diff --git a/Icons.md b/Icons.md index 0144f85..97711dc 100644 --- a/Icons.md +++ b/Icons.md @@ -9,7 +9,7 @@ | --------------- | ------------------------------- | | `123rf` | 123rf.com | | `adobestock` | stock.adobe.com | -| `applemusic` | music.apple.com | +| `applemusic` | music.apple.com | | `behance` | behance.net | | `bilibili` | bilibili.com | | `bitcoin` | - | @@ -74,10 +74,11 @@ | `steam` | steampowered.com | | `strava` | strava.com | | `telegram` | telegram.org | -| `tiktok` | tiktok.com | +| `tiktok` | tiktok.com | | `twitch` | twitch.tv | | `twitter` | twitter.com | | `unsplash` | unsplash.com | +| `x` | x.com | | `xda` | xda-developers.com | | `xing` | xing.com | | `ycombinator` | ycombinator.com | @@ -86,28 +87,26 @@ Usage : -``` +```yml {linenos=true} socialIcons: - name: "kofi" - title: "<custom title>" url: "https://kofi.com" - - name: "twitter" - title: "<custom title>" - url: "https://twitter.com" + - name: "x" + url: "https://x.com" ``` --- ## Share Icons -| Platform | -| --------------------------------------------------------------- | -| `twitter` (also generates hash tags from tags linked with post) | -| `linkedin` | -| `reddit` | -| `facebook` | -| `whatsapp` | -| `telegram` | +| Platform | +| ------------------------------------------------------------------- | +| `x` (also generates `#hashtags` from _tags_ linked with post) | +| `linkedin` | +| `reddit` | +| `facebook` | +| `whatsapp` | +| `telegram` | Usage: diff --git a/Installation.md b/Installation.md index 8a56031..ce51fd5 100644 --- a/Installation.md +++ b/Installation.md @@ -1,124 +1,165 @@ ## ToC -- [Guide](#guide) - - [Method 1](#method-1) - - [Method 2](#method-2) - - [Method 3](#method-3) - - [Finally ...](#finally-) -- [Videos featuring Papermod](#videos-featuring-papermod) -- [Sample config.yml](#sample-configyml) -- [Sample Page.md](#sample-pagemd) +- [Getting Started 🚀](#getting-started-) + - [Installing/Updating PaperMod](#installingupdating-papermod) + - [Finally set theme as PaperMod in your site config](#finally-set-theme-as-papermod-in-your-site-config) + - [Next up - Customizing PaperMod to suit your preferences.](#next-up---customizing-papermod-to-suit-your-preferences) +- [Support 🫶](#support-) +- [Videos featuring PaperMod](#videos-featuring-papermod) +- [Quick Links](#quick-links) +- [Sample `config.yml`](#sample-configyml) +- [Sample `Page.md`](#sample-pagemd) --- -## 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. +> - **We'll be using `yml/yaml` format for all examples down below, it is recommend to use `yaml` 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 needed. --- -## Guide +## Getting Started 🚀 -> Follow [Quick Start](https://gohugo.io/getting-started/quick-start/) guide to setup hugo and create a new site. +1. Follow **[Hugo Docs's - Quick Start](https://gohugo.io/getting-started/quick-start/)** guide to install Hugo. + <br>(Make sure you install **Hugo >= v0.112.4**) -**Prerequisites** +2. Create a new Hugo site + ```sh + hugo new site MyFreshWebsite --format yaml + # replace MyFreshWebsite with name of your website + ``` + Note: + - Older versions of Hugo may not support `--format yaml` + - Read more here about [Hugo Docs's - hugo new site command](https://gohugo.io/commands/hugo_new_site/#synopsis) -- [Install Hugo](https://gohugo.io/installation/) - Make sure you install latest version of **`hugo(>=0.83.0)`**. -- [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - necessary for Method 1 & 2. +After you have created a new site, follow the below steps to add **PaperMod** -**Create a new site** +### Installing/Updating PaperMod -- `hugo new site <name of site> --format yaml` -- `cd <name of site>` - -After you have created a new site, follow the below steps: - -### Method 1 - -Inside the folder of your Hugo site, run: - -```bash -git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1 -``` - -**Note**: You may use ` --branch v7.0` to end of above command if you want to stick to specific release. - -**Updating theme with Method 1** : +- Themes reside in `MyFreshWebsite/themes` directory. +- PaperMod will be installed in `MyFreshWebsite/themes/PaperMod` +> <details> +> <summary><b>Expand Method 1 - Git Clone</b></summary> +> +> **INSTALL** : Inside the folder of your Hugo site `MyFreshWebsite`, run: +> +> ```bash +> git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1 +> ``` +> +> You may use ` --branch v7.0` to end of above command if you want to stick to specific release. +> +> **UPDATE**: Inside the folder of your Hugo site `MyFreshWebsite`, run: +> > ```bash > cd themes/PaperMod > git pull > ``` +> +> </details> -### Method 2 - -you can use as [submodule](https://www.atlassian.com/git/tutorials/git-submodule) with - -```bash -git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod -git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically) -``` - -**Note**: You may use ` --branch v7.0` to end of above command if you want to stick to specific release. - -**Updating theme with Method 2** : +<br> +> <details> +> <summary><b>Expand Method 2 - Git Submodule (recomended)</b></summary> +> +> **INSTALL** : Inside the folder of your Hugo site `MyFreshWebsite`, run: +> +> ```bash +> git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod +> git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically) +> ``` +> +> You may use ` --branch v7.0` to end of above command if you want to stick to specific release. +> Read more about git submodules [here](https://www.atlassian.com/git/tutorials/git-submodule). +> +> **UPDATE**: Inside the folder of your Hugo site `MyFreshWebsite`, run: +> > ```bash > git submodule update --remote --merge > ``` +> +> </details> -### Method 3 +<br> -You can Download as Zip from Github Page and extract in your themes directory +> <details> +> <summary><b>Expand Method 3 - Download an unzip</b></summary> +> +> Download PaperMod source as Zip from Github Releases and extract in your themes directory at `MyFreshWebsite/themes/PaperMod` +> +> Direct Links: +> +> - [Master Branch (Latest)](https://github.com/adityatelange/hugo-PaperMod/archive/master.zip) +> - [v7.0](https://github.com/adityatelange/hugo-PaperMod/archive/v7.0.zip) +> - [v6.0](https://github.com/adityatelange/hugo-PaperMod/archive/v6.0.zip) +> - [v5.0](https://github.com/adityatelange/hugo-PaperMod/archive/v5.0.zip) +> - [v4.0](https://github.com/adityatelange/hugo-PaperMod/archive/v4.0.zip) +> - [v3.0](https://github.com/adityatelange/hugo-PaperMod/archive/v3.0.zip) +> - [v2.0](https://github.com/adityatelange/hugo-PaperMod/archive/v2.0.zip) +> - [v1.0](https://github.com/adityatelange/hugo-PaperMod/archive/v1.0.zip) +> +> </details> -Direct Links: +<br> -- [Master Branch (Latest)](https://github.com/adityatelange/hugo-PaperMod/archive/master.zip) -- [v7.0](https://github.com/adityatelange/hugo-PaperMod/archive/v7.0.zip) -- [v6.0](https://github.com/adityatelange/hugo-PaperMod/archive/v6.0.zip) -- [v5.0](https://github.com/adityatelange/hugo-PaperMod/archive/v5.0.zip) -- [v4.0](https://github.com/adityatelange/hugo-PaperMod/archive/v4.0.zip) -- [v3.0](https://github.com/adityatelange/hugo-PaperMod/archive/v3.0.zip) -- [v2.0](https://github.com/adityatelange/hugo-PaperMod/archive/v2.0.zip) -- [v1.0](https://github.com/adityatelange/hugo-PaperMod/archive/v1.0.zip) +> <details> +> <summary><b>Expand Method 4 - Hugo module</b></summary> +> +> **INSTALL** : +> +> - Install [Go programming language](https://go.dev/doc/install) in your operating system. +> +> - Intialize your own hugo mod +> +> ``` +> hugo mod init YOUR_OWN_GIT_REPOSITORY +> ``` +> +> - Add PaperMod in your `config.yml` file +> +> ```go {linenos=true} +> module: +> imports: +> - path: github.com/adityatelange/hugo-PaperMod +> ``` +> +> **UPDATE**: +> +> ``` +> hugo mod get -u +> ``` +> +> Read more : [Hugo Docs's - HUGO MODULES](https://gohugo.io/hugo-modules/use-modules/) +> +> </details> -**Updating theme with Method 3** : +### Finally set theme as PaperMod in your site config -- Download the version you wish to upgrade to and extract the new version in your themes directory at `themes/PaperMod`. -- ex. `v6.0` is already installed, `v7.0` should be downloaded using above links and extract the new version in your themes directory at `themes/PaperMod` +In `config.yml` add: -### Finally ... - -Add in `config.yml`: - -```yml -theme: "PaperMod" +```yml {linenos=true} +theme: ["PaperMod"] ``` -#### Additional Method (by [#701](https://github.com/adityatelange/hugo-PaperMod/pull/701)) +### Next up - Customizing PaperMod to suit your preferences. -- Install Go programming language in your operating system. -- Intialize your own hugo mod -- ```bash - hugo mod init YOUR_OWN_GIT_REPOSITORY` - ``` -- Add `PaperMod` in your `config.yml` file -- ```yaml - module: - imports: - - path: github.com/adityatelange/hugo-PaperMod - ``` - -**Updating theme** : - -```bash -hugo mod get -u -``` +- Your site will be blank after you set up for the very first time. +- You may go through this website's source code - [PaperMod's exampleSite's souce](https://github.com/adityatelange/hugo-PaperMod/tree/exampleSite) +- Scroll below this page where you will find more specific details about each section. +- Kindly go through all of the pages below to know how to configure PaperMod. --- -## Videos featuring Papermod +## Support 🫶 + +- Star 🌟 PaperMod's Github repository. +- Help spread the word about PaperMod by sharing it on social media and recommending it to your friends. 🗣️ +- You can also sponsor 🏅 on [Github Sponsors](https://github.com/sponsors/adityatelange) / [Ko-Fi](https://ko-fi.com/adityatelange). + +--- + +## Videos featuring PaperMod You can go through few videos which are available on YouTube for getting to know the creator's thoughts as well as the setup process. @@ -128,17 +169,15 @@ You can go through few videos which are available on YouTube for getting to know ## Quick Links -- ### [Features](./Features) +- ### [Papermod - Features](../papermod-features) -- ### [Icons](./Icons) +- ### [Papermod - FAQs](../papermod-how-to) -- ### [FAQs](./FAQs) +- ### [Papermod - Variables](../papermod-variables) -- ### [Variables](./Variables) +- ### [Papermod - Icons](../papermod-icons) -- ### [Translations](./Translations) - -- ### [ChangeLog](./ChangeLog) +- ### [ChangeLog](https://github.com/adityatelange/hugo-PaperMod/releases) --- @@ -228,8 +267,8 @@ params: Content: Welcome to my blog socialIcons: - - name: twitter - url: "https://twitter.com/" + - name: x + url: "https://x.com/" - name: stackoverflow url: "https://stackoverflow.com" - name: github @@ -262,6 +301,7 @@ params: distance: 1000 threshold: 0.4 minMatchCharLength: 0 + limit: 10 # refer: https://www.fusejs.io/api/methods.html#search keys: ["title", "permalink", "summary", "content"] menu: main: @@ -333,7 +373,7 @@ editPost: --- ``` -You can use it by creating `archetypes/posts.md` +You can use it by creating `archetypes/post.md` ```shell hugo new --kind post <name> diff --git a/Variables.md b/Variables.md index 2da5767..5098a21 100644 --- a/Variables.md +++ b/Variables.md @@ -32,14 +32,14 @@ | `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 | -| `ShareButtons` | list | ["linkedin", "twitter"] | To customize which share buttons to be enabled on page | +| `ShareButtons` | list | ["linkedin", "x"] | To customize which share buttons to be enabled on page | | `ShowWordCount` | boolean | true \| false | To word count to metadata | | `ShowRssButtonInSectionTermList` | boolean | true \| false | To show RSS icon in Section, Term and List pages | | `UseHugoToc` | boolean | true \| false | To use Hugo's default Toc instead of custom | | `comments` | boolean | true \| false | To show/hide comments | | `hideFooter` | boolean | true \| false | To Hide Footer Text om the end of page | | `CanonicalLinkText` | string | 'Originally published at' | To show text before canonical URL's hostname | -| `displayFullLangName` | boolean | true \| false | To show `languageName` under a language in Language switch header | +| `displayFullLangName` | boolean | true \| false | To show `languageName` under a language in Language switch header | | `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 | @@ -128,6 +128,7 @@ fuseOpts: distance: 1000 threshold: 0.4 minMatchCharLength: 0 + limit: 10 # refer: https://www.fusejs.io/api/methods.html#search keys: ["title", "permalink", "summary", "content"] ## can be less but not more than shown in list ``` @@ -135,12 +136,10 @@ fuseOpts: ```yml socialIcons: - - name: "<platform>" - title: "<custom title>" - url: "<link>" - - name: "<platform 2>" - title: "<custom title 2>" - url: "<link2>" + - name: "<platform>" + url: "<link>" + - name: "<platform 2>" + url: "<link2>" ``` #### editPost @@ -185,7 +184,7 @@ editPost: | `cover.responsiveImages` | boolean | true \| false | To enable/disable generation of responsive cover images | | `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 | -| `ShareButtons` | list | ["linkedin", "twitter"] | To customize which share buttons to be enabled on page | +| `ShareButtons` | list | ["linkedin", "x"] | To customize which share buttons to be enabled on page | | `ShowWordCount` | boolean | true \| false | To word count to metadata | | `ShowRssButtonInSectionTermList` | boolean | true \| false | To show RSS icon in Section, Term and List pages | | `UseHugoToc` | boolean | true \| false | To use Hugo's default Toc instead of custom |