PaperModX/exampleSite/content/docs/features/index.md at master

11 KiB

Raw Permalink Blame History

title	summary	date	author
PaperMod Features	Learn About All Features in original PaperMod	2021-01-20	Aditya Telange

source: https://adityatelange.github.io/hugo-PaperMod/posts/papermod/papermod-features/

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 converters if necessary.

Assets (js/css)

The following is enabled by default

minification - makes the assets size smallest as possible.
bundling - bundles all the styles in one single asset
fingerprint/integrity check.

Default Theme light/dark/auto

params:
    # defaultTheme: light
    # defaultTheme: dark
    defaultTheme: auto # to switch between dark or light according to browser theme

Theme Switch Toggle (enabled by default)

Shows icon besides title of page to change theme

To disable it :

disableThemeToggle: true

You can refer following table for better understanding...

`defaultTheme`	`disableThemeToggle`	checks local storage?	checks system theme?	Info
`auto`	true	No	Yes	only system theme
	false	Yes (if not->2)	Yes (2)	switch present
`dark`	true	No	No	force dark only
	false	Yes	No	switch present
`light`	true	No	No	force light only
	false	Yes	No	switch present

Archives Layout

Create a page with archive.md in content directory with following content

.
├── config.yml
├── content/
│   ├── archives.md   <--- Create archive.md here
│   └── posts/
├── static/
└── themes/
    └── PaperModX/

and add the following to it

---
title: "Archive"
layout: "archives"
url: "/archives/"
summary: archives
---

Note: Archives Layout does not support Multilingual Month Translations.

Regular Mode (default-mode)

Home-Info Mode

Use 1st entry as some Information

add following to config file

params:
    homeInfoParams:
        Title: Hi there wave
        Content: Can be Info, links, about...

    socialIcons: # optional
        - name: "<platform>"
          url: "<link>"
        - name: "<platform 2>"
          url: "<link2>"

Profile Mode

Shows Index/Home page as Full Page with Social Links and Image

add following to config file

params:
    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>"

Search Page

PaperModX uses Fuse.js Basic for seach functionality

Add the following to site config, config.yml

outputs:
    home:
        - HTML
        - RSS
        - JSON # is necessary

Create a page with search.md in content directory with following content

---
title: "Search" # in any language you want
layout: "search" # is necessary
# url: "/archive"
# description: "Description for Search"
summary: "search"
---

To hide a particular page from being searched, add it in post's fron't matter

---
searchHidden: true

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 !

Customizing Fusejs Options

Refer https://fusejs.io/api/options.html for Options, Add those as shown below.

params:
    fuseOpts:
        isCaseSensitive: false
        shouldSort: true
        location: 0
        distance: 1000
        threshold: 0.4
        minMatchCharLength: 0
        keys: ["title", "permalink", "summary", "content"]

Draft Page indication

adds [draft] mark to indicate draft pages.

Post Cover Image

In post's page-variables add :

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

When you include images in the Page Bundle, 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

params:
    cover:
        responsiveImages: false

To enable hyperlinks to the full image size on post pages, use

params:
    cover:
        linkFullImages: true

Displays Share Buttons at Bottom of each post

to show share buttons add

params:
    ShowShareButtons: true

Show post reading time

Displays Reading Time (the estimated time, in minutes, it takes to read the content.)

To show reading time add

Params:
    ShowReadingTime: true

Show Table of Contents (Toc) on blog post

Displays ToC on blog-pages

To show ToC add following to page-variables

ShowToc: true

To keep Toc Open by default on a post add following to page-variables:

TocOpen: true

Adds BreadCrumb Navigation above Post's Title to show subsections and Navigation to Home

params:
    ShowBreadCrumbs: true

Can be diabled for particular page's front-matter

---
ShowBreadCrumbs: false
---

Edit Link for Posts

Add a button to suggest changes by using the file path of the post to link to a edit destination.

For site config use:

Params:
    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

---
editPost:
    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

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. URL: "mailto://mail@example.com?subject=Suggesting changes for "

Multiple Authors

To Use multiple authors for a post, in post-variables:

---
author: ["Me", "You"]
---

To use Multiple Authors Site-wide, in config.yml:

params:
    author: ["Me", "You"]

Comments

to add comments, create a html file

layouts/partials/comments.html

and paste code provided by your comments provider

also in config add this

params:
    comments: true

AccessKeys

c - ToC Open/Close
g - Go To Top
h - Home (according to current lang)
t - Theme toggle
/ - Jumps to search page if in menu

What's AccessKeys ?

Enhanced SEO

Enabled only when env: production

Rich Results/Snippets Support

Twitter Cards 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, if present.
In the absence of a cover images, the first image from the images frontmatter (a list) is used.
```
images:
  - image_01.png
  - image_02.png
```
Finally, if neither of those are provided, twitter:image comes from the first Page Bundle 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, if present.
In the absence of a cover images, the first image from the images frontmatter (a list) is used.
```
images:
  - image_01.png
  - image_02.png
```
Finally, if neither of those are provided, og:image comes from the first Page Bundle 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.
```
videos:
  - filename01.mov
  - filename02.avi
```

Multilingual Support

Misc

Scroll-Bar themed (by default)

Smooth Scroll between in-page links (by default)

Scroll-to-Top Button (by default)

Displays a Scroll-to-Top button in right-bottom corner

11 KiB

Raw Permalink Blame History

Intro

Assets (js/css)

Default Theme light/dark/auto

Theme Switch Toggle (enabled by default)

Archives Layout

Regular Mode (default-mode)

Home-Info Mode

Profile Mode

Search Page

Draft Page indication

Post Cover Image

Show post reading time

Show Table of Contents (Toc) on blog post

Edit Link for Posts

Other Posts suggestion below a post

Multiple Authors

Comments

AccessKeys

Enhanced SEO

Twitter Cards Support

OpenGraph support

Multilingual Support

Misc

Scroll-Bar themed (by default)

Smooth Scroll between in-page links (by default)

Scroll-to-Top Button (by default)

Google Analytics integration

Syntax highlighting

RSS feeds

11 KiB Raw Permalink Blame History

Intro

Assets (js/css)

Default Theme light/dark/auto

Theme Switch Toggle (enabled by default)

Archives Layout

Regular Mode (default-mode)

Home-Info Mode

Profile Mode

Search Page

Draft Page indication

Post Cover Image

Share Buttons on post

Show post reading time

Show Table of Contents (Toc) on blog post

BreadCrumb Navigation

Edit Link for Posts

Other Posts suggestion below a post

Multiple Authors

Comments

AccessKeys

Enhanced SEO

Twitter Cards Support

OpenGraph support

Multilingual Support

Misc

Scroll-Bar themed (by default)

Smooth Scroll between in-page links (by default)

Scroll-to-Top Button (by default)

Google Analytics integration

Syntax highlighting

RSS feeds

11 KiB

Raw Permalink Blame History