diff options
Diffstat (limited to 'themes/CodeIT/exampleSite/content/posts/theme-documentation-basics')
9 files changed, 3099 insertions, 0 deletions
diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/basic-configuration-preview.png b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/basic-configuration-preview.png Binary files differnew file mode 100644 index 0000000..00a4e65 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/basic-configuration-preview.png diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/basic-configuration-preview.zh-cn.png b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/basic-configuration-preview.zh-cn.png Binary files differnew file mode 100644 index 0000000..1b1d293 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/basic-configuration-preview.zh-cn.png diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/complete-configuration-preview.png b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/complete-configuration-preview.png Binary files differnew file mode 100644 index 0000000..2772674 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/complete-configuration-preview.png diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/complete-configuration-preview.zh-cn.png b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/complete-configuration-preview.zh-cn.png Binary files differnew file mode 100644 index 0000000..7990929 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/complete-configuration-preview.zh-cn.png diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/featured-image.jpg b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/featured-image.jpg Binary files differnew file mode 100644 index 0000000..87f5401 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/featured-image.jpg diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.en.md b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.en.md new file mode 100644 index 0000000..7ffa5b9 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.en.md @@ -0,0 +1,1031 @@ +--- +weight: 1 +title: "Theme Documentation - Basics" +date: 2020-03-06T21:29:01+08:00 +lastmod: 2020-03-06T21:29:01+08:00 +draft: false +author: "Sunt Programator!" +authorLink: "https://suntprogramator.dev/" +description: "Discover what the Hugo - CodeIT theme is all about and the core-concepts behind it." +resources: + - name: "featured-image" + src: "featured-image.jpg" + +tags: ["installation", "configuration"] +categories: ["documentation"] + +lightgallery: true + +toc: + auto: false +--- + +Discover what the Hugo - **CodeIT** theme is all about and the core-concepts behind it. + +<!--more--> + +## 1 Requirements + +Thanks to the simplicity of Hugo, [Hugo](https://gohugo.io/) is the only dependency of this theme. + +Just install latest version of [:(far fa-file-archive fa-fw): Hugo (> 0.78.1)](https://gohugo.io/getting-started/installing/) for your OS (**Windows**, **Linux**, **macOS**). + +{{< admonition tip "Hugo extended version is recommended" >}} +Since some features of this theme need to processes :(fab fa-sass fa-fw): SCSS to :(fab fa-css3 fa-fw): CSS, it is recommended to use Hugo **extended** version for better experience. +{{< /admonition >}} + +## 2 Installation + +The following steps are here to help you initialize your new website. If you don’t know Hugo at all, we strongly suggest you learn more about it by following this [great documentation for beginners](https://gohugo.io/getting-started/quick-start/). + +### 2.1 Create Your Project + +Hugo provides a `new` command to create a new website: + +```bash +hugo new site my_website +cd my_website +``` + +### 2.2 Install the Theme + +The **CodeIT** theme’s repository is: [https://github.com/sunt-programator/CodeIT](https://github.com/sunt-programator/CodeIT). + +You can download the [latest release :(far fa-file-archive fa-fw): .zip file](https://github.com/sunt-programator/CodeIT/releases) of the theme and extract it in the `themes` directory. + +Alternatively, clone this repository to the `themes` directory: + +```bash +git clone https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +Or, create an empty git repository and make this repository a submodule of your site directory: + +```bash +git init +git submodule add https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +### 2.3 Basic Configuration {#basic-configuration} + +The following is a basic configuration for the CodeIT theme: + +```toml +baseURL = "http://example.org/" +# [en, zh-cn, fr, ...] determines default content language +defaultContentLanguage = "en" +# language code +languageCode = "en" +title = "My New Hugo Site" + +# Change the default theme to be use when building the site with Hugo +theme = "CodeIT" + +[params] + # CodeIT theme version + version = "0.2.X" + +[menu] + [[menu.main]] + identifier = "posts" + # you can add extra information before the name (HTML format is supported), such as icons + pre = "" + # you can add extra information after the name (HTML format is supported), such as icons + post = "" + name = "Posts" + url = "/posts/" + # title will be shown when you hover on this menu link + title = "" + weight = 1 + [[menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Tags" + url = "/tags/" + title = "" + weight = 2 + [[menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Categories" + url = "/categories/" + title = "" + weight = 3 + +# Markup related configuration in Hugo +[markup] + # Syntax Highlighting (https://gohugo.io/content-management/syntax-highlighting) + [markup.highlight] + # false is a necessary configuration (https://github.com/sunt-programator/CodeIT/issues/158) + noClasses = false +``` + +{{< admonition >}} +When building the website, you can set a theme by using `--theme` option. However, we suggest you modify the configuration file (**config.toml**) and set the theme as the default. +{{< /admonition >}} + +### 2.4 Create Your First Post + +Here is the way to create your first post: + +```bash +hugo new posts/first_post.md +``` + +Feel free to edit the post file by adding some sample content and replacing the title value in the beginning of the file. + +{{< admonition >}} +By default all posts and pages are created as a draft. If you want to render these pages, remove the property `draft: true` from the metadata, set the property `draft: false` or add `-D`/`--buildDrafts` parameter to `hugo` command. +{{< /admonition >}} + +### 2.5 Launching the Website Locally + +Launch by using the following command: + +```bash +hugo serve +``` + +Go to `http://localhost:1313`. + + + +{{< admonition tip >}} +When you run `hugo serve`, when the contents of the files change, the page automatically refreshes with the changes. +{{< /admonition >}} + +{{< admonition >}} +Since the theme use `.Scratch` in Hugo to implement some features, +it is highly recommended that you add `--disableFastRender` parameter to `hugo server` command for the live preview of the page you are editing. + +```bash +hugo serve --disableFastRender +``` + +{{< /admonition >}} + +### 2.6 Build the Website + +When your site is ready to deploy, run the following command: + +```bash +hugo +``` + +A `public` folder will be generated, containing all static content and assets for your website. It can now be deployed on any web server. + +{{< admonition tip >}} +The website can be automatically published and hosted with [Netlify](https://www.netlify.com/) (Read more about [Automated HUGO deployments with Netlify](https://www.netlify.com/blog/2015/07/30/hosting-hugo-on-netlifyinsanely-fast-deploys/)). +Alternatively, you can use [AWS Amplify](https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/), [Github pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/), [Render](https://gohugo.io/hosting-and-deployment/hosting-on-render/) and more... +{{< /admonition >}} + +## 3 Configuration + +### 3.1 Site Configuration {#site-configuration} + +In addition to [Hugo global configuration](https://gohugo.io/overview/configuration/) and [menu configuration](#basic-configuration), **CodeIT** lets you define the following parameters in your site configuration (here is a `config.toml`, whose values are default). + +Please open the code block below to view the complete sample configuration :(far fa-hand-point-down fa-fw):: + +```toml +[params] + # CodeIT theme version + version = "0.2.X" + # site description + description = "This is My New Hugo Site" + # site keywords + keywords = ["Theme", "Hugo"] + # site default theme ("light", "dark", "auto") + defaultTheme = "auto" + # public git repo url only then enableGitInfo is true + gitRepo = "" + # which hash function used for SRI, when empty, no SRI is used + # ("sha256", "sha384", "sha512", "md5") + fingerprint = "" + # date format + dateFormat = "2006-01-02" + # website images for Open Graph and Twitter Cards + images = ["/logo.png"] + + # App icon config + [params.app] + # optional site title override for the app when added to an iOS home screen or Android launcher + title = "CodeIT" + # whether to omit favicon resource links + noFavicon = false + # modern SVG favicon to use in place of older style .png and .ico files + svgFavicon = "" + # Android browser theme color + themeColor = "#ffffff" + # Safari mask icon color + iconColor = "#5bbad5" + # Windows v8-10 tile color + tileColor = "#da532c" + + # Search config + [params.search] + enable = true + # type of search engine ("lunr", "algolia") + type = "lunr" + # max index length of the chunked content + contentLength = 4000 + # placeholder of the search bar + placeholder = "" + # max number of results length + maxResultLength = 10 + # snippet length of the result + snippetLength = 30 + # HTML tag name of the highlight part in results + highlightTag = "em" + # whether to use the absolute URL based on the baseURL in search index + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" + + # Header config + [params.header] + # desktop header mode ("fixed", "normal", "auto") + desktopMode = "fixed" + # mobile header mode ("fixed", "normal", "auto") + mobileMode = "auto" + # Header title config + [params.header.title] + # URL of the LOGO + logo = "" + # title name + name = "" + # you can add extra information before the name (HTML format is supported), such as icons + pre = "" + # you can add extra information after the name (HTML format is supported), such as icons + post = "" + # whether to use typeit animation for title name + typeit = false + + # Footer config + [params.footer] + enable = true + # Custom content (HTML format is supported) + custom = '' + # whether to show Hugo and theme info + hugo = true + # whether to show copyright info + copyright = true + # whether to show the author + author = true + # Site creation time + since = 2019 + # ICP info only in China (HTML format is supported) + icp = "" + # license info (HTML format is supported) + license = '<a rel="license external nofollow noopener noreffer" href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank">CC BY-NC 4.0</a>' + + # Section (all posts) page config + [params.section] + # special amount of posts in each section page + paginate = 20 + # date format (month and day) + dateFormat = "01-02" + # amount of RSS pages + rss = 10 + + # List (category or tag) page config + [params.list] + # special amount of posts in each list page + paginate = 20 + # date format (month and day) + dateFormat = "01-02" + # amount of RSS pages + rss = 10 + + # Home page config + [params.home] + # amount of RSS pages + rss = 10 + # Home page profile + [params.home.profile] + enable = true + # Gravatar Email for preferred avatar in home page + gravatarEmail = "" + # URL of avatar shown in home page + avatarURL = "/images/avatar.png" + # title shown in home page (HTML format is supported) + title = "" + # subtitle shown in home page + subtitle = "This is My New Hugo Site" + # whether to use typeit animation for subtitle + typeit = true + # whether to show social links + social = true + # disclaimer (HTML format is supported) + disclaimer = "" + # Home page posts + [params.home.posts] + enable = true + # special amount of posts in each home posts page + paginate = 6 + # replaced with hiddenFromHomePage in params.page + # default behavior when you don't set "hiddenFromHomePage" in front matter + defaultHiddenFromHomePage = false + + # Social config about the author + [params.social] + GitHub = "xxxx" + Linkedin = "" + Twitter = "xxxx" + Instagram = "xxxx" + Facebook = "xxxx" + Telegram = "xxxx" + Medium = "" + Gitlab = "" + Youtubelegacy = "" + Youtubecustom = "" + Youtubechannel = "" + Tumblr = "" + Quora = "" + Keybase = "" + Pinterest = "" + Reddit = "" + Codepen = "" + FreeCodeCamp = "" + Bitbucket = "" + Stackoverflow = "" + Weibo = "" + Odnoklassniki = "" + VK = "" + Flickr = "" + Xing = "" + Snapchat = "" + Soundcloud = "" + Spotify = "" + Bandcamp = "" + Paypal = "" + Fivehundredpx = "" + Mix = "" + Goodreads = "" + Lastfm = "" + Foursquare = "" + Hackernews = "" + Kickstarter = "" + Patreon = "" + Steam = "" + Twitch = "" + Strava = "" + Skype = "" + Whatsapp = "" + Zhihu = "" + Douban = "" + Angellist = "" + Slidershare = "" + Jsfiddle = "" + Deviantart = "" + Behance = "" + Dribbble = "" + Wordpress = "" + Vine = "" + Googlescholar = "" + Researchgate = "" + Mastodon = "" + Thingiverse = "" + Devto = "" + Gitea = "" + XMPP = "" + Matrix = "" + Bilibili = "" + Email = "xxxx@xxxx.com" + RSS = true # + + # Page config + [params.page] + # whether to hide a page from home page + hiddenFromHomePage = false + # whether to hide a page from search results + hiddenFromSearch = false + # whether to enable twemoji + twemoji = false + # whether to enable lightgallery + lightgallery = false + # whether to enable the ruby extended syntax + ruby = true + # whether to enable the fraction extended syntax + fraction = true + # whether to enable the fontawesome extended syntax + fontawesome = true + # whether to show link to Raw Markdown content of the content + linkToMarkdown = true + # whether to show the full text content in RSS + rssFullText = false + # Table of the contents config + [params.page.toc] + # whether to enable the table of the contents + enable = true + # whether to keep the static table of the contents in front of the post + keepStatic = true + # whether to make the table of the contents in the sidebar automatically collapsed + auto = true + # {{< link "https://katex.org/" KaTeX >}} mathematical formulas + [params.page.math] + enable = true + # default block delimiter is $$ ... $$ and \\[ ... \\] + blockLeftDelimiter = "" + blockRightDelimiter = "" + # default inline delimiter is $ ... $ and \\( ... \\) + inlineLeftDelimiter = "" + inlineRightDelimiter = "" + # KaTeX extension copy_tex + copyTex = true + # KaTeX extension mhchem + mhchem = true + # Code config + [params.page.code] + # whether to show the copy button of the code block + copy = true + # the maximum number of lines of displayed code by default + maxShownLines = 10 + # {{< link "https://docs.mapbox.com/mapbox-gl-js" "Mapbox GL JS" >}} config + [params.page.mapbox] + # access token of Mapbox GL JS + accessToken = "" + # style for the light theme + lightStyle = "mapbox://styles/mapbox/light-v9" + # style for the dark theme + darkStyle = "mapbox://styles/mapbox/dark-v9" + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#navigationcontrol" NavigationControl >}} + navigation = true + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#geolocatecontrol" GeolocateControl >}} + geolocate = true + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#scalecontrol" ScaleControl >}} + scale = true + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#fullscreencontrol" FullscreenControl >}} + fullscreen = true + # social share links in post page + [params.page.share] + enable = true + Twitter = true + Facebook = true + Linkedin = false + Whatsapp = true + Pinterest = false + Tumblr = false + HackerNews = false + Reddit = false + VK = false + Buffer = false + Xing = false + Line = true + Instapaper = false + Pocket = false + Digg = false + Stumbleupon = false + Flipboard = false + Weibo = true + Renren = false + Myspace = true + Blogger = true + Baidu = false + Odnoklassniki = false + Evernote = true + Skype = false + Trello = false + Mix = false + # Comment config + [params.page.comment] + enable = true + # {{< link "https://disqus.com/" Disqus >}} comment config + [params.page.comment.disqus] + enable = false + # Disqus shortname to use Disqus in posts + shortname = "" + # {{< link "https://github.com/gitalk/gitalk" Gitalk >}} comment config + [params.page.comment.gitalk] + enable = false + owner = "" + repo = "" + clientId = "" + clientSecret = "" + # {{< link "https://github.com/xCss/Valine" Valine >}} comment config + [params.page.comment.valine] + enable = false + appId = "" + appKey = "" + placeholder = "" + avatar = "mp" + meta= "" + pageSize = 10 + lang = "" + visitor = true + recordIP = true + highlight = true + enableQQ = false + serverURLs = "" + # emoji data file name, default is "google.yml" + # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # located in "themes/CodeIT/assets/data/emoji/" directory + # you can store your own data files in the same path under your project: + # "assets/data/emoji/" + emoji = "" + # {{< link "https://developers.facebook.com/docs/plugins/comments" "Facebook comment" >}} config + [params.page.comment.facebook] + enable = false + width = "100%" + numPosts = 10 + appId = "" + languageCode = "" + # {{< link "https://comments.app/" "Telegram comments" >}} config + [params.page.comment.telegram] + enable = false + siteID = "" + limit = 5 + height = "" + color = "" + colorful = true + dislikes = false + outlined = false + # {{< link "https://commento.io/" "Commento" >}} comment config + [params.page.comment.commento] + enable = false + # {{< link "https://utteranc.es/" "Utterances" >}} comment config + [params.page.comment.utterances] + enable = false + # owner/repo + repo = "" + issueTerm = "pathname" + label = "" + lightTheme = "github-light" + darkTheme = "github-dark" + # Third-party library config + [params.page.library] + [params.page.library.css] + # someCSS = "some.css" + # located in "assets/" + # Or + # someCSS = "https://cdn.example.com/some.css" + [params.page.library.js] + # someJavascript = "some.js" + # located in "assets/" + # Or + # someJavascript = "https://cdn.example.com/some.js" + # Page SEO config + [params.page.seo] + # image URL + images = [] + # Publisher info + [params.page.seo.publisher] + name = "" + logoUrl = "" + + # TypeIt config + [params.typeit] + # typing speed between each step (measured in milliseconds) + speed = 100 + # blinking speed of the cursor (measured in milliseconds) + cursorSpeed = 1000 + # character used for the cursor (HTML format is supported) + cursorChar = "|" + # cursor duration after typing finishing (measured in milliseconds, "-1" means unlimited) + duration = -1 + + # Site verification code config for Google/Bing/Yandex/Pinterest/Baidu + [params.verification] + google = "" + bing = "" + yandex = "" + pinterest = "" + baidu = "" + + # Site SEO config + [params.seo] + # image URL + image = "" + # thumbnail URL + thumbnailUrl = "" + + # Analytics config + [params.analytics] + enable = false + # Google Analytics + [params.analytics.google] + id = "" + # whether to anonymize IP + anonymizeIP = true + # Fathom Analytics + [params.analytics.fathom] + id = "" + # server url for your tracker if you're self hosting + server = "" + # {{< version 0.1.0 >}} Plausible Analytics + [params.analytics.plausible] + domain = "" + + # Cookie consent config + [params.cookieconsent] + enable = true + # text strings used for Cookie consent banner + [params.cookieconsent.content] + message = "" + dismiss = "" + link = "" + + # CDN config for third-party library files + [params.cdn] + # CDN data file name, disabled by default + # ("jsdelivr.yml") + # located in "themes/CodeIT/assets/data/cdn/" directory + # you can store your own data files in the same path under your project: + # "assets/data/cdn/" + data = "" + + # Compatibility config + [params.compatibility] + # whether to use Polyfill.io to be compatible with older browsers + polyfill = false + # whether to use object-fit-images to be compatible with older browsers + objectFit = false + +# Markup related config in Hugo +[markup] + # {{< link "https://gohugo.io/content-management/syntax-highlighting" "Syntax Highlighting" >}} + [markup.highlight] + codeFences = true + guessSyntax = true + lineNos = true + lineNumbersInTable = true + # false is a necessary configuration + # ({{< link "https://github.com/sunt-programator/CodeIT/issues/158" >}}) + noClasses = false + # Goldmark is from Hugo 0.60 the default library used for Markdown + [markup.goldmark] + [markup.goldmark.extensions] + definitionList = true + footnote = true + linkify = true + strikethrough = true + table = true + taskList = true + typographer = true + [markup.goldmark.renderer] + # whether to use HTML tags directly in the document + unsafe = true + # Table Of Contents settings + [markup.tableOfContents] + startLevel = 2 + endLevel = 6 + +# Author config +[author] + name = "xxxx" + email = "" + link = "" + +# Sitemap config +[sitemap] + changefreq = "weekly" + filename = "sitemap.xml" + priority = 0.5 + +# {{< link "https://gohugo.io/content-management/urls#permalinks" "Permalinks config" >}} +[Permalinks] + # posts = ":year/:month/:filename" + posts = ":filename" + +# {{< link "https://gohugo.io/about/hugo-and-gdpr/" "Privacy config" >}} +[privacy] + # privacy of the Google Analytics (replaced by params.analytics.google) + [privacy.googleAnalytics] + # ... + [privacy.twitter] + enableDNT = true + [privacy.youtube] + privacyEnhanced = true + +# Options to make output .md files +[mediaTypes] + [mediaTypes."text/plain"] + suffixes = ["md"] + +# Options to make output .md files +[outputFormats.MarkDown] + mediaType = "text/plain" + isPlainText = true + isHTML = false + +# Options to make hugo output files +[outputs] + home = ["HTML", "RSS", "JSON"] + page = ["HTML", "MarkDown"] + section = ["HTML", "RSS"] + taxonomy = ["HTML", "RSS"] + taxonomyTerm = ["HTML"] +``` + +{{< admonition >}} +Note that some of these parameters are explained in details in other sections of this documentation. +{{< /admonition >}} + +{{< admonition note "Hugo environments" >}} +Default environments are `development` with `hugo serve` and `production` with `hugo`. + +Due to limitations in the local `development` environment, +the **comment system**, **CDN** and **fingerprint** will not be enabled in the `development` environment. + +You could enable these features with `hugo serve -e production`. +{{< /admonition >}} + +{{< admonition tip "Tips about CDN Configuration" >}} + +```toml +[params.cdn] + # CDN data file name, disabled by default + # ("jsdelivr.yml") + data = "" +``` + +The default CDN data file is located in `themes/CodeIT/assets/data/cdn/` directory. +You can store your own data file in the same path under your project: `assets/data/cdn/`. +{{< /admonition >}} + +{{< admonition tip "Tips about social Configuration" >}} + +You can directly set your ID to get a default social link and its icon: + +```toml +[params.social] + Mastodon = "@xxxx" +``` + +The social link generated is `https://mastodon.technology/@xxxx`. + +Or You can set more options through a dict: + +```toml +[params.social] + [params.social.Mastodon] + # weight when arranging icons (the greater the weight, the later the icon is positioned) + weight = 0 + # your social ID + id = "@xxxx" + # prefix of your social link + prefix = "https://mastodon.social/" + # content hovering on the icon + title = "Mastodon" +``` + +The default data of all supported social links is located in `themes/CodeIT/assets/data/social.yaml`, +which is you can refer to. +{{< /admonition >}} + + + +### 3.2 Favicons, Browserconfig, Manifest + +It is recommended to put your own favicons: + +- apple-touch-icon.png (180x180) +- favicon-32x32.png (32x32) +- favicon-16x16.png (16x16) +- mstile-150x150.png (150x150) +- android-chrome-192x192.png (192x192) +- android-chrome-512x512.png (512x512) + +into `/static`. They’re easily created via [https://realfavicongenerator.net/](https://realfavicongenerator.net/). + +Customize `browserconfig.xml` and `site.webmanifest` to set theme-color and background-color. + +### 3.3 Style Customization + +{{< admonition >}} +Hugo **extended** version is necessary for the style customization. +{{< /admonition >}} + +**CodeIT** theme has been built to be as configurable as possible by defining custom `.scss` style files. + +The directory including the custom `.scss` style files is `assets/css` relative to **your project root directory**. + +In `assets/css/_override.scss`, you can override the variables in `themes/CodeIT/assets/css/_variables.scss` to customize the style. + +Here is a example: + +```scss +@import url("https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext"); +$code-font-family: Fira Mono, Source Code Pro, Menlo, Consolas, Monaco, + monospace; +``` + +In `assets/css/_custom.scss`, you can add some css style code to customize the style. + +## 4 Multilingual and i18n + +**CodeIT** theme is fully compatible with Hugo multilingual mode, which provides in-browser language switching. + + + +### 4.1 Compatibility {#language-compatibility} + +| Language | Hugo Code | HTML `lang` Attribute | Theme Docs | Lunr.js Support | +| :------------------- | :-------: | :-------------------: | :---------------------------: | :---------------------------: | +| English | `en` | `en` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| Simplified Chinese | `zh-cn` | `zh-CN` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| French | `fr` | `fr` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Polish | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| Brazilian Portuguese | `pt-br` | `pt-BR` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Italian | `it` | `it` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Spanish | `es` | `es` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| German | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| German | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Serbian | `sr` | `sr` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| Russian | `ru` | `ru` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Romanian | `ro` | `ro` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Vietnamese | `vi` | `vi` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | + +### 4.2 Basic Configuration + +After learning [how Hugo handle multilingual websites](https://gohugo.io/content-management/multilingual), define your languages in your [site configuration](#site-configuration). + +For example with English, Chinese and French website: + +```toml +# [en, zh-cn, fr, pl, ...] determines default content language +defaultContentLanguage = "en" + +[languages] + [languages.en] + weight = 1 + title = "My New Hugo Site" + languageCode = "en" + languageName = "English" + [[languages.en.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Posts" + url = "/posts/" + title = "" + weight = 1 + [[languages.en.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Tags" + url = "/tags/" + title = "" + weight = 2 + [[languages.en.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Categories" + url = "/categories/" + title = "" + weight = 3 + + [languages.zh-cn] + weight = 2 + title = "我的全新 Hugo 网站" + # language code, CN only here + languageCode = "zh-CN" + languageName = "简体中文" + # whether to include Chinese/Japanese/Korean + hasCJKLanguage = true + [[languages.zh-cn.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "文章" + url = "/posts/" + title = "" + weight = 1 + [[languages.zh-cn.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "标签" + url = "/tags/" + title = "" + weight = 2 + [[languages.zh-cn.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "分类" + url = "/categories/" + title = "" + weight = 3 + + [languages.fr] + weight = 3 + title = "Mon nouveau site Hugo" + languageCode = "fr" + languageName = "Français" + [[languages.fr.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Postes" + url = "/posts/" + title = "" + weight = 1 + [[languages.fr.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Balises" + url = "/tags/" + title = "" + weight = 2 + [[languages.fr.menu.main]] + identifier = "categories" + name = "Catégories" + pre = "" + post = "" + url = "/categories/" + title = "" + weight = 3 +``` + +Then, for each new page, append the language code to the file name. + +Single file `my-page.md` is split in three files: + +- in English: `my-page.en.md` +- in Chinese: `my-page.zh-cn.md` +- in French: `my-page.fr.md` + +{{< admonition >}} +Be aware that only translated pages are displayed in menu. It’s not replaced with default language content. +{{< /admonition >}} + +{{< admonition tip >}} +Use [Front Matter parameter](https://gohugo.io/content-management/multilingual#translate-your-content) to translate urls too. +{{< /admonition >}} + +### 4.3 Overwrite Translation Strings + +Translations strings are used for common default values used in the theme. Translations are available in [some languages](#language-compatibility), but you may use another language or want to override default values. + +To override these values, create a new file in your local i18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/CodeIT/i18n/en.toml`. + +By the way, as these translations could be used by other people, please take the time to propose a translation by [:(fas fa-code-branch fa-fw): making a PR](https://github.com/sunt-programator/CodeIT/pulls) to the theme! + +## 5 Search + +Based on [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/), searching is supported in **CodeIT** theme. + +### 5.1 Output Configuration + +In order to generate `index.json` for searching, add `JSON` output file type to the `home` of the `outputs` part in your [site configuration](#site-configuration). + +```toml +[outputs] + home = ["HTML", "RSS", "JSON"] +``` + +### 5.2 Search Configuration + +Based on `index.json` generated by Hugo, you could activate searching. + +Here is the search configuration in your [site configuration](#site-configuration): + +```toml +[params.search] + enable = true + # type of search engine ("lunr", "algolia") + type = "lunr" + # max index length of the chunked content + contentLength = 4000 + # placeholder of the search bar + placeholder = "" + # max number of results length + maxResultLength = 10 + # snippet length of the result + snippetLength = 30 + # HTML tag name of the highlight part in results + highlightTag = "em" + # whether to use the absolute URL based on the baseURL in search index + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" +``` + +{{< admonition note "How to choose search engine?" >}} +The following is a comparison of two search engines: + +- `lunr`: simple, no need to synchronize `index.json`, no limit for `contentLength`, + but high bandwidth and low performance (Especially for Chinese which needs a large segmentit library) +- `algolia`: high performance and low bandwidth, but need to synchronize `index.json` and limit for `contentLength` + +The content of the post is separated by `h2` and `h3` HTML tag to improve query performance and basically implement full-text search. +`contentLength` is used to limit the max index length of the part starting with `h2` and `h3` HTML tag. +{{< /admonition >}} + +{{< admonition tip "Tips about algolia" >}} +You need to upload `index.json` files to algolia to activate searching. +You could upload the `index.json` files by browsers but a CLI tool may be better. +[Algolia Atomic](https://github.com/chrisdmacrae/atomic-algolia) is a good choice. +To be compatible with Hugo multilingual mode, +you need to upload different `index.json` for each language to the different index of algolia, such as `zh-cn/index.json` or `fr/index.json`... +{{< /admonition >}} diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.fr.md b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.fr.md new file mode 100644 index 0000000..a423913 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.fr.md @@ -0,0 +1,1036 @@ +--- +weight: 1 +title: "Thème Documentation - Concepts de Base" +date: 2020-03-06T21:40:32+08:00 +lastmod: 2020-03-06T21:40:32+08:00 +draft: false +author: "Sunt Programator!" +authorLink: "https://suntprogramator.dev/" +description: "Découvrez en quoi consiste le thème Hugo - CodeIT et les concepts fondamentaux qui le sous-tendent." +resources: + - name: "featured-image" + src: "featured-image.jpg" + +tags: ["installation", "configuration"] +categories: ["documentation"] + +lightgallery: true + +toc: + auto: false +--- + +Découvrez en quoi consiste le thème Hugo - **CodeIT** et les concepts fondamentaux qui le sous-tendent. + +<!--more--> + +{{< admonition warning >}} +Sorry, this article has not been completely translated into **French**. +Welcome to take the time to propose a translation by [:(fas fa-code-branch fa-fw): making a PR](https://github.com/sunt-programator/CodeIT/pulls) to the theme! +{{< /admonition >}} + +## 1 Requirements + +Thanks to the simplicity of Hugo, [Hugo](https://gohugo.io/) is the only dependency of this theme. + +Just install latest version of [:(far fa-file-archive fa-fw): Hugo (> 0.78.1)](https://gohugo.io/getting-started/installing/) for your OS (**Windows**, **Linux**, **macOS**). + +{{< admonition tip "Hugo extended version is recommended" >}} +Since some features of this theme need to processes :(fab fa-sass fa-fw): SCSS to :(fab fa-css3 fa-fw): CSS, it is recommended to use Hugo **extended** version for better experience. +{{< /admonition >}} + +## 2 Installation + +The following steps are here to help you initialize your new website. If you don’t know Hugo at all, we strongly suggest you learn more about it by following this [great documentation for beginners](https://gohugo.io/getting-started/quick-start/). + +### 2.1 Create Your Project + +Hugo provides a `new` command to create a new website: + +```bash +hugo new site my_website +cd my_website +``` + +### 2.2 Install the Theme + +The **CodeIT** theme’s repository is: [https://github.com/sunt-programator/CodeIT](https://github.com/sunt-programator/CodeIT). + +You can download the [latest release :(far fa-file-archive fa-fw): .zip file](https://github.com/sunt-programator/CodeIT/releases) of the theme and extract it in the `themes` directory. + +Alternatively, clone this repository to the `themes` directory: + +```bash +git clone https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +Or, create an empty git repository and make this repository a submodule of your site directory: + +```bash +git init +git submodule add https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +### 2.3 Basic Configuration {#basic-configuration} + +The following is a basic configuration for the CodeIT theme: + +```toml +baseURL = "http://example.org/" +# [en, zh-cn, fr, ...] determines default content language +defaultContentLanguage = "en" +# language code +languageCode = "en" +title = "My New Hugo Site" + +# Change the default theme to be use when building the site with Hugo +theme = "CodeIT" + +[params] + # CodeIT theme version + version = "0.2.X" + +[menu] + [[menu.main]] + identifier = "posts" + # you can add extra information before the name (HTML format is supported), such as icons + pre = "" + # you can add extra information after the name (HTML format is supported), such as icons + post = "" + name = "Posts" + url = "/posts/" + # title will be shown when you hover on this menu link + title = "" + weight = 1 + [[menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Tags" + url = "/tags/" + title = "" + weight = 2 + [[menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Categories" + url = "/categories/" + title = "" + weight = 3 + +# Markup related configuration in Hugo +[markup] + # Syntax Highlighting (https://gohugo.io/content-management/syntax-highlighting) + [markup.highlight] + # false is a necessary configuration (https://github.com/sunt-programator/CodeIT/issues/158) + noClasses = false +``` + +{{< admonition >}} +When building the website, you can set a theme by using `--theme` option. However, we suggest you modify the configuration file (**config.toml**) and set the theme as the default. +{{< /admonition >}} + +### 2.4 Create Your First Post + +Here is the way to create your first post: + +```bash +hugo new posts/first_post.md +``` + +Feel free to edit the post file by adding some sample content and replacing the title value in the beginning of the file. + +{{< admonition >}} +By default all posts and pages are created as a draft. If you want to render these pages, remove the property `draft: true` from the metadata, set the property `draft: false` or add `-D`/`--buildDrafts` parameter to `hugo` command. +{{< /admonition >}} + +### 2.5 Launching the Website Locally + +Launch by using the following command: + +```bash +hugo serve +``` + +Go to `http://localhost:1313`. + + + +{{< admonition tip >}} +When you run `hugo serve`, when the contents of the files change, the page automatically refreshes with the changes. +{{< /admonition >}} + +{{< admonition >}} +Since the theme use `.Scratch` in Hugo to implement some features, +it is highly recommended that you add `--disableFastRender` parameter to `hugo server` command for the live preview of the page you are editing. + +```bash +hugo serve --disableFastRender +``` + +{{< /admonition >}} + +### 2.6 Build the Website + +When your site is ready to deploy, run the following command: + +```bash +hugo +``` + +A `public` folder will be generated, containing all static content and assets for your website. It can now be deployed on any web server. + +{{< admonition tip >}} +The website can be automatically published and hosted with [Netlify](https://www.netlify.com/) (Read more about [Automated HUGO deployments with Netlify](https://www.netlify.com/blog/2015/07/30/hosting-hugo-on-netlifyinsanely-fast-deploys/)). +Alternatively, you can use [AWS Amplify](https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/), [Github pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/), [Render](https://gohugo.io/hosting-and-deployment/hosting-on-render/) and more... +{{< /admonition >}} + +## 3 Configuration + +### 3.1 Site Configuration {#site-configuration} + +In addition to [Hugo global configuration](https://gohugo.io/overview/configuration/) and [menu configuration](#basic-configuration), **CodeIT** lets you define the following parameters in your site configuration (here is a `config.toml`, whose values are default). + +Please open the code block below to view the complete sample configuration :(far fa-hand-point-down fa-fw):: + +```toml +[params] + # CodeIT theme version + version = "0.2.X" + # site description + description = "This is My New Hugo Site" + # site keywords + keywords = ["Theme", "Hugo"] + # site default theme ("light", "dark", "auto") + defaultTheme = "auto" + # public git repo url only then enableGitInfo is true + gitRepo = "" + # which hash function used for SRI, when empty, no SRI is used + # ("sha256", "sha384", "sha512", "md5") + fingerprint = "" + # date format + dateFormat = "2006-01-02" + # website images for Open Graph and Twitter Cards + images = ["/logo.png"] + + # App icon config + [params.app] + # optional site title override for the app when added to an iOS home screen or Android launcher + title = "CodeIT" + # whether to omit favicon resource links + noFavicon = false + # modern SVG favicon to use in place of older style .png and .ico files + svgFavicon = "" + # Android browser theme color + themeColor = "#ffffff" + # Safari mask icon color + iconColor = "#5bbad5" + # Windows v8-10 tile color + tileColor = "#da532c" + + # Search config + [params.search] + enable = true + # type of search engine ("lunr", "algolia") + type = "lunr" + # max index length of the chunked content + contentLength = 4000 + # placeholder of the search bar + placeholder = "" + # max number of results length + maxResultLength = 10 + # snippet length of the result + snippetLength = 30 + # HTML tag name of the highlight part in results + highlightTag = "em" + # whether to use the absolute URL based on the baseURL in search index + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" + + # Header config + [params.header] + # desktop header mode ("fixed", "normal", "auto") + desktopMode = "fixed" + # mobile header mode ("fixed", "normal", "auto") + mobileMode = "auto" + # Header title config + [params.header.title] + # URL of the LOGO + logo = "" + # title name + name = "" + # you can add extra information before the name (HTML format is supported), such as icons + pre = "" + # you can add extra information after the name (HTML format is supported), such as icons + post = "" + # whether to use typeit animation for title name + typeit = false + + # Footer config + [params.footer] + enable = true + # Custom content (HTML format is supported) + custom = '' + # whether to show Hugo and theme info + hugo = true + # whether to show copyright info + copyright = true + # whether to show the author + author = true + # Site creation time + since = 2019 + # ICP info only in China (HTML format is supported) + icp = "" + # license info (HTML format is supported) + license = '<a rel="license external nofollow noopener noreffer" href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank">CC BY-NC 4.0</a>' + + # Section (all posts) page config + [params.section] + # special amount of posts in each section page + paginate = 20 + # date format (month and day) + dateFormat = "01-02" + # amount of RSS pages + rss = 10 + + # List (category or tag) page config + [params.list] + # special amount of posts in each list page + paginate = 20 + # date format (month and day) + dateFormat = "01-02" + # amount of RSS pages + rss = 10 + + # Home page config + [params.home] + # amount of RSS pages + rss = 10 + # Home page profile + [params.home.profile] + enable = true + # Gravatar Email for preferred avatar in home page + gravatarEmail = "" + # URL of avatar shown in home page + avatarURL = "/images/avatar.png" + # title shown in home page (HTML format is supported) + title = "" + # subtitle shown in home page + subtitle = "This is My New Hugo Site" + # whether to use typeit animation for subtitle + typeit = true + # whether to show social links + social = true + # disclaimer (HTML format is supported) + disclaimer = "" + # Home page posts + [params.home.posts] + enable = true + # special amount of posts in each home posts page + paginate = 6 + # replaced with hiddenFromHomePage in params.page + # default behavior when you don't set "hiddenFromHomePage" in front matter + defaultHiddenFromHomePage = false + + # Social config about the author + [params.social] + GitHub = "xxxx" + Linkedin = "" + Twitter = "xxxx" + Instagram = "xxxx" + Facebook = "xxxx" + Telegram = "xxxx" + Medium = "" + Gitlab = "" + Youtubelegacy = "" + Youtubecustom = "" + Youtubechannel = "" + Tumblr = "" + Quora = "" + Keybase = "" + Pinterest = "" + Reddit = "" + Codepen = "" + FreeCodeCamp = "" + Bitbucket = "" + Stackoverflow = "" + Weibo = "" + Odnoklassniki = "" + VK = "" + Flickr = "" + Xing = "" + Snapchat = "" + Soundcloud = "" + Spotify = "" + Bandcamp = "" + Paypal = "" + Fivehundredpx = "" + Mix = "" + Goodreads = "" + Lastfm = "" + Foursquare = "" + Hackernews = "" + Kickstarter = "" + Patreon = "" + Steam = "" + Twitch = "" + Strava = "" + Skype = "" + Whatsapp = "" + Zhihu = "" + Douban = "" + Angellist = "" + Slidershare = "" + Jsfiddle = "" + Deviantart = "" + Behance = "" + Dribbble = "" + Wordpress = "" + Vine = "" + Googlescholar = "" + Researchgate = "" + Mastodon = "" + Thingiverse = "" + Devto = "" + Gitea = "" + XMPP = "" + Matrix = "" + Bilibili = "" + Email = "xxxx@xxxx.com" + RSS = true # + + # Page config + [params.page] + # whether to hide a page from home page + hiddenFromHomePage = false + # whether to hide a page from search results + hiddenFromSearch = false + # whether to enable twemoji + twemoji = false + # whether to enable lightgallery + lightgallery = false + # whether to enable the ruby extended syntax + ruby = true + # whether to enable the fraction extended syntax + fraction = true + # whether to enable the fontawesome extended syntax + fontawesome = true + # whether to show link to Raw Markdown content of the content + linkToMarkdown = true + # whether to show the full text content in RSS + rssFullText = false + # Table of the contents config + [params.page.toc] + # whether to enable the table of the contents + enable = true + # whether to keep the static table of the contents in front of the post + keepStatic = true + # whether to make the table of the contents in the sidebar automatically collapsed + auto = true + # {{< link "https://katex.org/" KaTeX >}} mathematical formulas + [params.page.math] + enable = true + # default block delimiter is $$ ... $$ and \\[ ... \\] + blockLeftDelimiter = "" + blockRightDelimiter = "" + # default inline delimiter is $ ... $ and \\( ... \\) + inlineLeftDelimiter = "" + inlineRightDelimiter = "" + # KaTeX extension copy_tex + copyTex = true + # KaTeX extension mhchem + mhchem = true + # Code config + [params.page.code] + # whether to show the copy button of the code block + copy = true + # the maximum number of lines of displayed code by default + maxShownLines = 10 + # {{< link "https://docs.mapbox.com/mapbox-gl-js" "Mapbox GL JS" >}} config + [params.page.mapbox] + # access token of Mapbox GL JS + accessToken = "" + # style for the light theme + lightStyle = "mapbox://styles/mapbox/light-v9" + # style for the dark theme + darkStyle = "mapbox://styles/mapbox/dark-v9" + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#navigationcontrol" NavigationControl >}} + navigation = true + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#geolocatecontrol" GeolocateControl >}} + geolocate = true + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#scalecontrol" ScaleControl >}} + scale = true + # whether to add {{< link "https://docs.mapbox.com/mapbox-gl-js/api#fullscreencontrol" FullscreenControl >}} + fullscreen = true + # social share links in post page + [params.page.share] + enable = true + Twitter = true + Facebook = true + Linkedin = false + Whatsapp = true + Pinterest = false + Tumblr = false + HackerNews = false + Reddit = false + VK = false + Buffer = false + Xing = false + Line = true + Instapaper = false + Pocket = false + Digg = false + Stumbleupon = false + Flipboard = false + Weibo = true + Renren = false + Myspace = true + Blogger = true + Baidu = false + Odnoklassniki = false + Evernote = true + Skype = false + Trello = false + Mix = false + # Comment config + [params.page.comment] + enable = true + # {{< link "https://disqus.com/" Disqus >}} comment config + [params.page.comment.disqus] + enable = false + # Disqus shortname to use Disqus in posts + shortname = "" + # {{< link "https://github.com/gitalk/gitalk" Gitalk >}} comment config + [params.page.comment.gitalk] + enable = false + owner = "" + repo = "" + clientId = "" + clientSecret = "" + # {{< link "https://github.com/xCss/Valine" Valine >}} comment config + [params.page.comment.valine] + enable = false + appId = "" + appKey = "" + placeholder = "" + avatar = "mp" + meta= "" + pageSize = 10 + lang = "" + visitor = true + recordIP = true + highlight = true + enableQQ = false + serverURLs = "" + # emoji data file name, default is "google.yml" + # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # located in "themes/CodeIT/assets/data/emoji/" directory + # you can store your own data files in the same path under your project: + # "assets/data/emoji/" + emoji = "" + # {{< link "https://developers.facebook.com/docs/plugins/comments" "Facebook comment" >}} config + [params.page.comment.facebook] + enable = false + width = "100%" + numPosts = 10 + appId = "" + languageCode = "" + # {{< link "https://comments.app/" "Telegram comments" >}} config + [params.page.comment.telegram] + enable = false + siteID = "" + limit = 5 + height = "" + color = "" + colorful = true + dislikes = false + outlined = false + # {{< link "https://commento.io/" "Commento" >}} comment config + [params.page.comment.commento] + enable = false + # {{< link "https://utteranc.es/" "Utterances" >}} comment config + [params.page.comment.utterances] + enable = false + # owner/repo + repo = "" + issueTerm = "pathname" + label = "" + lightTheme = "github-light" + darkTheme = "github-dark" + # Third-party library config + [params.page.library] + [params.page.library.css] + # someCSS = "some.css" + # located in "assets/" + # Or + # someCSS = "https://cdn.example.com/some.css" + [params.page.library.js] + # someJavascript = "some.js" + # located in "assets/" + # Or + # someJavascript = "https://cdn.example.com/some.js" + # Page SEO config + [params.page.seo] + # image URL + images = [] + # Publisher info + [params.page.seo.publisher] + name = "" + logoUrl = "" + + # TypeIt config + [params.typeit] + # typing speed between each step (measured in milliseconds) + speed = 100 + # blinking speed of the cursor (measured in milliseconds) + cursorSpeed = 1000 + # character used for the cursor (HTML format is supported) + cursorChar = "|" + # cursor duration after typing finishing (measured in milliseconds, "-1" means unlimited) + duration = -1 + + # Site verification code config for Google/Bing/Yandex/Pinterest/Baidu + [params.verification] + google = "" + bing = "" + yandex = "" + pinterest = "" + baidu = "" + + # Site SEO config + [params.seo] + # image URL + image = "" + # thumbnail URL + thumbnailUrl = "" + + # Analytics config + [params.analytics] + enable = false + # Google Analytics + [params.analytics.google] + id = "" + # whether to anonymize IP + anonymizeIP = true + # Fathom Analytics + [params.analytics.fathom] + id = "" + # server url for your tracker if you're self hosting + server = "" + # {{< version 0.1.0 >}} Plausible Analytics + [params.analytics.plausible] + domain = "" + + # Cookie consent config + [params.cookieconsent] + enable = true + # text strings used for Cookie consent banner + [params.cookieconsent.content] + message = "" + dismiss = "" + link = "" + + # CDN config for third-party library files + [params.cdn] + # CDN data file name, disabled by default + # ("jsdelivr.yml") + # located in "themes/CodeIT/assets/data/cdn/" directory + # you can store your own data files in the same path under your project: + # "assets/data/cdn/" + data = "" + + # Compatibility config + [params.compatibility] + # whether to use Polyfill.io to be compatible with older browsers + polyfill = false + # whether to use object-fit-images to be compatible with older browsers + objectFit = false + +# Markup related config in Hugo +[markup] + # {{< link "https://gohugo.io/content-management/syntax-highlighting" "Syntax Highlighting" >}} + [markup.highlight] + codeFences = true + guessSyntax = true + lineNos = true + lineNumbersInTable = true + # false is a necessary configuration + # ({{< link "https://github.com/sunt-programator/CodeIT/issues/158" >}}) + noClasses = false + # Goldmark is from Hugo 0.60 the default library used for Markdown + [markup.goldmark] + [markup.goldmark.extensions] + definitionList = true + footnote = true + linkify = true + strikethrough = true + table = true + taskList = true + typographer = true + [markup.goldmark.renderer] + # whether to use HTML tags directly in the document + unsafe = true + # Table Of Contents settings + [markup.tableOfContents] + startLevel = 2 + endLevel = 6 + +# Author config +[author] + name = "xxxx" + email = "" + link = "" + +# Sitemap config +[sitemap] + changefreq = "weekly" + filename = "sitemap.xml" + priority = 0.5 + +# {{< link "https://gohugo.io/content-management/urls#permalinks" "Permalinks config" >}} +[Permalinks] + # posts = ":year/:month/:filename" + posts = ":filename" + +# {{< link "https://gohugo.io/about/hugo-and-gdpr/" "Privacy config" >}} +[privacy] + # privacy of the Google Analytics (replaced by params.analytics.google) + [privacy.googleAnalytics] + # ... + [privacy.twitter] + enableDNT = true + [privacy.youtube] + privacyEnhanced = true + +# Options to make output .md files +[mediaTypes] + [mediaTypes."text/plain"] + suffixes = ["md"] + +# Options to make output .md files +[outputFormats.MarkDown] + mediaType = "text/plain" + isPlainText = true + isHTML = false + +# Options to make hugo output files +[outputs] + home = ["HTML", "RSS", "JSON"] + page = ["HTML", "MarkDown"] + section = ["HTML", "RSS"] + taxonomy = ["HTML", "RSS"] + taxonomyTerm = ["HTML"] +``` + +{{< admonition >}} +Note that some of these parameters are explained in details in other sections of this documentation. +{{< /admonition >}} + +{{< admonition note "Hugo environments" >}} +Default environments are `development` with `hugo serve` and `production` with `hugo`. + +Due to limitations in the local `development` environment, +the **comment system**, **CDN** and **fingerprint** will not be enabled in the `development` environment. + +You could enable these features with `hugo serve -e production`. +{{< /admonition >}} + +{{< admonition tip "Tips about CDN Configuration" >}} + +```toml +[params.cdn] + # CDN data file name, disabled by default + # ("jsdelivr.yml") + data = "" +``` + +The default CDN data file is located in `themes/CodeIT/assets/data/cdn/` directory. +You can store your own data file in the same path under your project: `assets/data/cdn/`. +{{< /admonition >}} + +{{< admonition tip "Tips about social Configuration" >}} + +You can directly set your ID to get a default social link and its icon: + +```toml +[params.social] + Mastodon = "@xxxx" +``` + +The social link generated is `https://mastodon.technology/@xxxx`. + +Or You can set more options through a dict: + +```toml +[params.social] + [params.social.Mastodon] + # weight when arranging icons (the greater the weight, the later the icon is positioned) + weight = 0 + # your social ID + id = "@xxxx" + # prefix of your social link + prefix = "https://mastodon.social/" + # content hovering on the icon + title = "Mastodon" +``` + +The default data of all supported social links is located in `themes/CodeIT/assets/data/social.yaml`, +which is you can refer to. +{{< /admonition >}} + + + +### 3.2 Favicons, Browserconfig, Manifest + +It is recommended to put your own favicons: + +- apple-touch-icon.png (180x180) +- favicon-32x32.png (32x32) +- favicon-16x16.png (16x16) +- mstile-150x150.png (150x150) +- android-chrome-192x192.png (192x192) +- android-chrome-512x512.png (512x512) + +into `/static`. They’re easily created via [https://realfavicongenerator.net/](https://realfavicongenerator.net/). + +Customize `browserconfig.xml` and `site.webmanifest` to set theme-color and background-color. + +### 3.3 Style Customization + +{{< admonition >}} +Hugo **extended** version is necessary for the style customization. +{{< /admonition >}} + +**CodeIT** theme has been built to be as configurable as possible by defining custom `.scss` style files. + +The directory including the custom `.scss` style files is `assets/css` relative to **your project root directory**. + +In `assets/css/_override.scss`, you can override the variables in `themes/CodeIT/assets/css/_variables.scss` to customize the style. + +Here is a example: + +```scss +@import url("https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext"); +$code-font-family: Fira Mono, Source Code Pro, Menlo, Consolas, Monaco, + monospace; +``` + +In `assets/css/_custom.scss`, you can add some css style code to customize the style. + +## 4 Multilingual and i18n + +**CodeIT** theme is fully compatible with Hugo multilingual mode, which provides in-browser language switching. + + + +### 4.1 Compatibility {#language-compatibility} + +| Language | Hugo Code | HTML `lang` Attribute | Theme Docs | Lunr.js Support | +| :------------------- | :-------: | :-------------------: | :---------------------------: | :---------------------------: | +| English | `en` | `en` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| Simplified Chinese | `zh-cn` | `zh-CN` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| French | `fr` | `fr` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Polish | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| Brazilian Portuguese | `pt-br` | `pt-BR` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Italian | `it` | `it` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Spanish | `es` | `es` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| German | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| German | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Serbian | `sr` | `sr` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| Russian | `ru` | `ru` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Romanian | `ro` | `ro` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| Vietnamese | `vi` | `vi` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | + +### 4.2 Basic Configuration + +After learning [how Hugo handle multilingual websites](https://gohugo.io/content-management/multilingual), define your languages in your [site configuration](#site-configuration). + +For example with English, Chinese and French website: + +```toml +# [en, zh-cn, fr, pl, ...] determines default content language +defaultContentLanguage = "en" + +[languages] + [languages.en] + weight = 1 + title = "My New Hugo Site" + languageCode = "en" + languageName = "English" + [[languages.en.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Posts" + url = "/posts/" + title = "" + weight = 1 + [[languages.en.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Tags" + url = "/tags/" + title = "" + weight = 2 + [[languages.en.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Categories" + url = "/categories/" + title = "" + weight = 3 + + [languages.zh-cn] + weight = 2 + title = "我的全新 Hugo 网站" + # language code, CN only here + languageCode = "zh-CN" + languageName = "简体中文" + # whether to include Chinese/Japanese/Korean + hasCJKLanguage = true + [[languages.zh-cn.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "文章" + url = "/posts/" + title = "" + weight = 1 + [[languages.zh-cn.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "标签" + url = "/tags/" + title = "" + weight = 2 + [[languages.zh-cn.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "分类" + url = "/categories/" + title = "" + weight = 3 + + [languages.fr] + weight = 3 + title = "Mon nouveau site Hugo" + languageCode = "fr" + languageName = "Français" + [[languages.fr.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Postes" + url = "/posts/" + title = "" + weight = 1 + [[languages.fr.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Balises" + url = "/tags/" + title = "" + weight = 2 + [[languages.fr.menu.main]] + identifier = "categories" + name = "Catégories" + pre = "" + post = "" + url = "/categories/" + title = "" + weight = 3 +``` + +Then, for each new page, append the language code to the file name. + +Single file `my-page.md` is split in three files: + +- in English: `my-page.en.md` +- in Chinese: `my-page.zh-cn.md` +- in French: `my-page.fr.md` + +{{< admonition >}} +Be aware that only translated pages are displayed in menu. It’s not replaced with default language content. +{{< /admonition >}} + +{{< admonition tip >}} +Use [Front Matter parameter](https://gohugo.io/content-management/multilingual#translate-your-content) to translate urls too. +{{< /admonition >}} + +### 4.3 Overwrite Translation Strings + +Translations strings are used for common default values used in the theme. Translations are available in [some languages](#language-compatibility), but you may use another language or want to override default values. + +To override these values, create a new file in your local i18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/CodeIT/i18n/en.toml`. + +By the way, as these translations could be used by other people, please take the time to propose a translation by [:(fas fa-code-branch fa-fw): making a PR](https://github.com/sunt-programator/CodeIT/pulls) to the theme! + +## 5 Search + +Based on [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/), searching is supported in **CodeIT** theme. + +### 5.1 Output Configuration + +In order to generate `index.json` for searching, add `JSON` output file type to the `home` of the `outputs` part in your [site configuration](#site-configuration). + +```toml +[outputs] + home = ["HTML", "RSS", "JSON"] +``` + +### 5.2 Search Configuration + +Based on `index.json` generated by Hugo, you could activate searching. + +Here is the search configuration in your [site configuration](#site-configuration): + +```toml +[params.search] + enable = true + # type of search engine ("lunr", "algolia") + type = "lunr" + # max index length of the chunked content + contentLength = 4000 + # placeholder of the search bar + placeholder = "" + # max number of results length + maxResultLength = 10 + # snippet length of the result + snippetLength = 30 + # HTML tag name of the highlight part in results + highlightTag = "em" + # whether to use the absolute URL based on the baseURL in search index + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" +``` + +{{< admonition note "How to choose search engine?" >}} +The following is a comparison of two search engines: + +- `lunr`: simple, no need to synchronize `index.json`, no limit for `contentLength`, + but high bandwidth and low performance (Especially for Chinese which needs a large segmentit library) +- `algolia`: high performance and low bandwidth, but need to synchronize `index.json` and limit for `contentLength` + +The content of the post is separated by `h2` and `h3` HTML tag to improve query performance and basically implement full-text search. +`contentLength` is used to limit the max index length of the part starting with `h2` and `h3` HTML tag. +{{< /admonition >}} + +{{< admonition tip "Tips about algolia" >}} +You need to upload `index.json` files to algolia to activate searching. +You could upload the `index.json` files by browsers but a CLI tool may be better. +[Algolia Atomic](https://github.com/chrisdmacrae/atomic-algolia) is a good choice. +To be compatible with Hugo multilingual mode, +you need to upload different `index.json` for each language to the different index of algolia, such as `zh-cn/index.json` or `fr/index.json`... +{{< /admonition >}} diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md new file mode 100644 index 0000000..06029e5 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md @@ -0,0 +1,1032 @@ +--- +weight: 1 +title: "主题文档 - 基本概念" +date: 2020-03-06T21:40:32+08:00 +lastmod: 2020-03-06T21:40:32+08:00 +draft: false +author: "Sunt Programator!" +authorLink: "https://suntprogramator.dev/" +description: "探索 Hugo - CodeIT 主题的全部内容和背后的核心概念." +resources: + - name: "featured-image" + src: "featured-image.jpg" + +tags: ["installation", "configuration"] +categories: ["documentation"] + +lightgallery: true + +toc: + auto: false +--- + +探索 Hugo - **CodeIT** 主题的全部内容和背后的核心概念. + +<!--more--> + +## 1 准备 + +由于 Hugo 提供的便利性, [Hugo](https://gohugo.io/) 本身是这个主题唯一的依赖. + +直接安装满足你操作系统 (**Windows**, **Linux**, **macOS**) 的最新版本 [:(far fa-file-archive fa-fw): Hugo (> 0.78.1)](https://gohugo.io/getting-started/installing/). + +{{< admonition tip "推荐使用 Hugo extended 版本" >}} +由于这个主题的一些特性需要将 :(fab fa-sass fa-fw): SCSS 转换为 :(fab fa-css3 fa-fw): CSS, 推荐使用 Hugo **extended** 版本来获得更好的使用体验. +{{< /admonition >}} + +## 2 安装 + +以下步骤可帮助你初始化新网站. 如果你根本不了解 Hugo, 我们强烈建议你按照此 [快速入门文档](https://gohugo.io/getting-started/quick-start/) 进一步了解它. + +### 2.1 创建你的项目 + +Hugo 提供了一个 `new` 命令来创建一个新的网站: + +```bash +hugo new site my_website +cd my_website +``` + +### 2.2 安装主题 + +**CodeIT** 主题的仓库是: [https://github.com/sunt-programator/CodeIT](https://github.com/sunt-programator/CodeIT). + +你可以下载主题的 [最新版本 :(far fa-file-archive fa-fw): .zip 文件](https://github.com/sunt-programator/CodeIT/releases) 并且解压放到 `themes` 目录. + +另外, 也可以直接把这个主题克隆到 `themes` 目录: + +```bash +git clone https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +或者, 初始化你的项目目录为 git 仓库, 并且把主题仓库作为你的网站目录的子模块: + +```bash +git init +git submodule add https://github.com/sunt-programator/CodeIT.git themes/CodeIT +``` + +### 2.3 基础配置 {#basic-configuration} + +以下是 CodeIT 主题的基本配置: + +```toml +baseURL = "http://example.org/" +# [en, zh-cn, fr, ...] 设置默认的语言 +defaultContentLanguage = "zh-cn" +# 网站语言, 仅在这里 CN 大写 +languageCode = "zh-CN" +# 是否包括中日韩文字 +hasCJKLanguage = true +# 网站标题 +title = "我的全新 Hugo 网站" + +# 更改使用 Hugo 构建网站时使用的默认主题 +theme = "CodeIT" + +[params] + # CodeIT 主题版本 + version = "0.2.X" + +[menu] + [[menu.main]] + identifier = "posts" + # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标 + pre = "" + # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标 + post = "" + name = "文章" + url = "/posts/" + # 当你将鼠标悬停在此菜单链接上时, 将显示的标题 + title = "" + weight = 1 + [[menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "标签" + url = "/tags/" + title = "" + weight = 2 + [[menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "分类" + url = "/categories/" + title = "" + weight = 3 + +# Hugo 解析文档的配置 +[markup] + # 语法高亮设置 (https://gohugo.io/content-management/syntax-highlighting) + [markup.highlight] + # false 是必要的设置 (https://github.com/sunt-programator/CodeIT/issues/158) + noClasses = false +``` + +{{< admonition >}} +在构建网站时, 你可以使用 `--theme` 选项设置主题. 但是, 我建议你修改配置文件 (**config.toml**) 将本主题设置为默认主题. +{{< /admonition >}} + +### 2.4 创建你的第一篇文章 + +以下是创建第一篇文章的方法: + +```bash +hugo new posts/first_post.md +``` + +通过添加一些示例内容并替换文件开头的标题, 你可以随意编辑文章. + +{{< admonition >}} +默认情况下, 所有文章和页面均作为草稿创建. 如果想要渲染这些页面, 请从元数据中删除属性 `draft: true`, 设置属性 `draft: false` 或者为 `hugo` 命令添加 `-D`/`--buildDrafts` 参数. +{{< /admonition >}} + +### 2.5 在本地启动网站 + +使用以下命令启动网站: + +```bash +hugo serve +``` + +去查看 `http://localhost:1313`. + + + +{{< admonition tip >}} +当你运行 `hugo serve` 时, 当文件内容更改时, 页面会随着更改自动刷新. +{{< /admonition >}} + +{{< admonition >}} +由于本主题使用了 Hugo 中的 `.Scratch` 来实现一些特性, +非常建议你为 `hugo server` 命令添加 `--disableFastRender` 参数来实时预览你正在编辑的文章页面. + +```bash +hugo serve --disableFastRender +``` + +{{< /admonition >}} + +### 2.6 构建网站 + +当你准备好部署你的网站时, 运行以下命令: + +```bash +hugo +``` + +会生成一个 `public` 目录, 其中包含你网站的所有静态内容和资源. 现在可以将其部署在任何 Web 服务器上. + +{{< admonition tip >}} +网站内容可以通过 [Netlify](https://www.netlify.com/) 自动发布和托管 (了解有关[通过 Netlify 进行 HUGO 自动化部署](https://www.netlify.com/blog/2015/07/30/hosting-hugo-on-netlifyinsanely-fast-deploys/) 的更多信息). +或者, 您可以使用 [AWS Amplify](https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/), [Github pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/), [Render](https://gohugo.io/hosting-and-deployment/hosting-on-render/) 以及更多... +{{< /admonition >}} + +## 3 配置 + +### 3.1 网站配置 {#site-configuration} + +除了 [Hugo 全局配置](https://gohugo.io/overview/configuration/) 和 [菜单配置](#basic-configuration) 之外, **CodeIT** 主题还允许您在网站配置中定义以下参数 (这是一个示例 `config.toml`, 其内容为默认值). + +请打开下面的代码块查看完整的示例配置 :(far fa-hand-point-down fa-fw):: + +```toml +[params] + # CodeIT 主题版本 + version = "0.2.X" + # 网站描述 + description = "这是我的全新 Hugo 网站" + # 网站关键词 + keywords = ["Theme", "Hugo"] + # 网站默认主题样式 ("light", "dark", "auto") + defaultTheme = "auto" + # 公共 git 仓库路径，仅在 enableGitInfo 设为 true 时有效 + gitRepo = "" + # 哪种哈希函数用来 SRI, 为空时表示不使用 SRI + # ("sha256", "sha384", "sha512", "md5") + fingerprint = "" + # 日期格式 + dateFormat = "2006-01-02" + # 网站图片, 用于 Open Graph 和 Twitter Cards + images = ["/logo.png"] + + # 应用图标配置 + [params.app] + # 当添加到 iOS 主屏幕或者 Android 启动器时的标题, 覆盖默认标题 + title = "CodeIT" + # 是否隐藏网站图标资源链接 + noFavicon = false + # 更现代的 SVG 网站图标, 可替代旧的 .png 和 .ico 文件 + svgFavicon = "" + # Android 浏览器主题色 + themeColor = "#ffffff" + # Safari 图标颜色 + iconColor = "#5bbad5" + # Windows v8-10磁贴颜色 + tileColor = "#da532c" + + # 搜索配置 + [params.search] + enable = true + # 搜索引擎的类型 ("lunr", "algolia") + type = "lunr" + # 文章内容最长索引长度 + contentLength = 4000 + # 搜索框的占位提示语 + placeholder = "" + # 最大结果数目 + maxResultLength = 10 + # 结果内容片段长度 + snippetLength = 50 + # 搜索结果中高亮部分的 HTML 标签 + highlightTag = "em" + # 是否在搜索索引中使用基于 baseURL 的绝对路径 + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" + + # 页面头部导航栏配置 + [params.header] + # 桌面端导航栏模式 ("fixed", "normal", "auto") + desktopMode = "fixed" + # 移动端导航栏模式 ("fixed", "normal", "auto") + mobileMode = "auto" + # 页面头部导航栏标题配置 + [params.header.title] + # LOGO 的 URL + logo = "" + # 标题名称 + name = "" + # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标 + pre = "" + # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标 + post = "" + # 是否为标题显示打字机动画 + typeit = false + + # 页面底部信息配置 + [params.footer] + enable = true + # 自定义内容 (支持 HTML 格式) + custom = '' + # 是否显示 Hugo 和主题信息 + hugo = true + # 是否显示版权信息 + copyright = true + # 是否显示作者 + author = true + # 网站创立年份 + since = 2019 + # ICP 备案信息，仅在中国使用 (支持 HTML 格式) + icp = "" + # 许可协议信息 (支持 HTML 格式) + license = '<a rel="license external nofollow noopener noreffer" href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank">CC BY-NC 4.0</a>' + + # Section (所有文章) 页面配置 + [params.section] + # section 页面每页显示文章数量 + paginate = 20 + # 日期格式 (月和日) + dateFormat = "01-02" + # RSS 文章数目 + rss = 10 + + # List (目录或标签) 页面配置 + [params.list] + # list 页面每页显示文章数量 + paginate = 20 + # 日期格式 (月和日) + dateFormat = "01-02" + # RSS 文章数目 + rss = 10 + + # 主页配置 + [params.home] + # RSS 文章数目 + rss = 10 + # 主页个人信息 + [params.home.profile] + enable = true + # Gravatar 邮箱，用于优先在主页显示的头像 + gravatarEmail = "" + # 主页显示头像的 URL + avatarURL = "/images/avatar.png" + # 主页显示的网站标题 (支持 HTML 格式) + title = "" + # 主页显示的网站副标题 + subtitle = "这是我的全新 Hugo 网站" + # 是否为副标题显示打字机动画 + typeit = true + # 是否显示社交账号 + social = true + # 免责声明 (支持 HTML 格式) + disclaimer = "" + # 主页文章列表 + [params.home.posts] + enable = true + # 主页每页显示文章数量 + paginate = 6 + # 被 params.page 中的 hiddenFromHomePage 替代 + # 当你没有在文章前置参数中设置 "hiddenFromHomePage" 时的默认行为 + defaultHiddenFromHomePage = false + + # 作者的社交信息设置 + [params.social] + GitHub = "xxxx" + Linkedin = "" + Twitter = "xxxx" + Instagram = "xxxx" + Facebook = "xxxx" + Telegram = "xxxx" + Medium = "" + Gitlab = "" + Youtubelegacy = "" + Youtubecustom = "" + Youtubechannel = "" + Tumblr = "" + Quora = "" + Keybase = "" + Pinterest = "" + Reddit = "" + Codepen = "" + FreeCodeCamp = "" + Bitbucket = "" + Stackoverflow = "" + Weibo = "" + Odnoklassniki = "" + VK = "" + Flickr = "" + Xing = "" + Snapchat = "" + Soundcloud = "" + Spotify = "" + Bandcamp = "" + Paypal = "" + Fivehundredpx = "" + Mix = "" + Goodreads = "" + Lastfm = "" + Foursquare = "" + Hackernews = "" + Kickstarter = "" + Patreon = "" + Steam = "" + Twitch = "" + Strava = "" + Skype = "" + Whatsapp = "" + Zhihu = "" + Douban = "" + Angellist = "" + Slidershare = "" + Jsfiddle = "" + Deviantart = "" + Behance = "" + Dribbble = "" + Wordpress = "" + Vine = "" + Googlescholar = "" + Researchgate = "" + Mastodon = "" + Thingiverse = "" + Devto = "" + Gitea = "" + XMPP = "" + Matrix = "" + Bilibili = "" + Email = "xxxx@xxxx.com" + RSS = true # + + # 文章页面配置 + [params.page] + # 是否在主页隐藏一篇文章 + hiddenFromHomePage = false + # 是否在搜索结果中隐藏一篇文章 + hiddenFromSearch = false + # 是否使用 twemoji + twemoji = false + # 是否使用 lightgallery + lightgallery = false + # 是否使用 ruby 扩展语法 + ruby = true + # 是否使用 fraction 扩展语法 + fraction = true + # 是否使用 fontawesome 扩展语法 + fontawesome = true + # 是否在文章页面显示原始 Markdown 文档链接 + linkToMarkdown = true + # 是否在 RSS 中显示全文内容 + rssFullText = false + # 目录配置 + [params.page.toc] + # 是否使用目录 + enable = true + # 是否保持使用文章前面的静态目录 + keepStatic = true + # 是否使侧边目录自动折叠展开 + auto = true + # 代码配置 + [params.page.code] + # 是否显示代码块的复制按钮 + copy = true + # 默认展开显示的代码行数 + maxShownLines = 10 + # {{< link "https://katex.org/" KaTeX >}} 数学公式 + [params.page.math] + enable = true + # 默认块定界符是 $$ ... $$ 和 \\[ ... \\] + blockLeftDelimiter = "" + blockRightDelimiter = "" + # 默认行内定界符是 $ ... $ 和 \\( ... \\) + inlineLeftDelimiter = "" + inlineRightDelimiter = "" + # KaTeX 插件 copy_tex + copyTex = true + # KaTeX 插件 mhchem + mhchem = true + # {{< link "https://docs.mapbox.com/mapbox-gl-js" "Mapbox GL JS" >}} 配置 + [params.page.mapbox] + # Mapbox GL JS 的 access token + accessToken = "" + # 浅色主题的地图样式 + lightStyle = "mapbox://styles/mapbox/light-v9" + # 深色主题的地图样式 + darkStyle = "mapbox://styles/mapbox/dark-v9" + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#navigationcontrol" NavigationControl >}} + navigation = true + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#geolocatecontrol" GeolocateControl >}} + geolocate = true + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#scalecontrol" ScaleControl >}} + scale = true + # 是否添加 {{< link "https://docs.mapbox.com/mapbox-gl-js/api#fullscreencontrol" FullscreenControl >}} + fullscreen = true + # 文章页面的分享信息设置 + [params.page.share] + enable = true + Twitter = true + Facebook = true + Linkedin = false + Whatsapp = true + Pinterest = false + Tumblr = false + HackerNews = false + Reddit = false + VK = false + Buffer = false + Xing = false + Line = true + Instapaper = false + Pocket = false + Digg = false + Stumbleupon = false + Flipboard = false + Weibo = true + Renren = false + Myspace = true + Blogger = true + Baidu = false + Odnoklassniki = false + Evernote = true + Skype = false + Trello = false + Mix = false + # 评论系统设置 + [params.page.comment] + enable = true + # {{< link "https://disqus.com/" Disqus >}} 评论系统设置 + [params.page.comment.disqus] + enable = false + # Disqus 的 shortname，用来在文章中启用 Disqus 评论系统 + shortname = "" + # {{< link "https://github.com/gitalk/gitalk" Gitalk >}} 评论系统设置 + [params.page.comment.gitalk] + enable = false + owner = "" + repo = "" + clientId = "" + clientSecret = "" + # {{< link "https://github.com/xCss/Valine" Valine >}} 评论系统设置 + [params.page.comment.valine] + enable = false + appId = "" + appKey = "" + placeholder = "" + avatar = "mp" + meta= "" + pageSize = 10 + lang = "" + visitor = true + recordIP = true + highlight = true + enableQQ = false + serverURLs = "" + # emoji 数据文件名称, 默认是 "google.yml" + # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # 位于 "themes/CodeIT/assets/data/emoji/" 目录 + # 可以在你的项目下相同路径存放你自己的数据文件: + # "assets/data/emoji/" + emoji = "" + # {{< link "https://developers.facebook.com/docs/plugins/comments" "Facebook 评论系统" >}}设置 + [params.page.comment.facebook] + enable = false + width = "100%" + numPosts = 10 + appId = "" + languageCode = "zh_CN" + # {{< link "https://comments.app/" "Telegram Comments" >}} 评论系统设置 + [params.page.comment.telegram] + enable = false + siteID = "" + limit = 5 + height = "" + color = "" + colorful = true + dislikes = false + outlined = false + # {{< link "https://commento.io/" "Commento" >}} 评论系统设置 + [params.page.comment.commento] + enable = false + # {{< link "https://utteranc.es/" "Utterances" >}} 评论系统设置 + [params.page.comment.utterances] + enable = false + # owner/repo + repo = "" + issueTerm = "pathname" + label = "" + lightTheme = "github-light" + darkTheme = "github-dark" + # 第三方库配置 + [params.page.library] + [params.page.library.css] + # someCSS = "some.css" + # 位于 "assets/" + # 或者 + # someCSS = "https://cdn.example.com/some.css" + [params.page.library.js] + # someJavascript = "some.js" + # 位于 "assets/" + # 或者 + # someJavascript = "https://cdn.example.com/some.js" + # 页面 SEO 配置 + [params.page.seo] + # 图片 URL + images = [] + # 出版者信息 + [params.page.seo.publisher] + name = "" + logoUrl = "" + + # TypeIt 配置 + [params.typeit] + # 每一步的打字速度 (单位是毫秒) + speed = 100 + # 光标的闪烁速度 (单位是毫秒) + cursorSpeed = 1000 + # 光标的字符 (支持 HTML 格式) + cursorChar = "|" + # 打字结束之后光标的持续时间 (单位是毫秒, "-1" 代表无限大) + duration = -1 + + # 网站验证代码，用于 Google/Bing/Yandex/Pinterest/Baidu + [params.verification] + google = "" + bing = "" + yandex = "" + pinterest = "" + baidu = "" + + # 网站 SEO 配置 + [params.seo] + # 图片 URL + image = "" + # 缩略图 URL + thumbnailUrl = "" + + # 网站分析配置 + [params.analytics] + enable = false + # Google Analytics + [params.analytics.google] + id = "" + # 是否匿名化用户 IP + anonymizeIP = true + # Fathom Analytics + [params.analytics.fathom] + id = "" + # 自行托管追踪器时的主机路径 + server = "" + # {{< version 0.1.0 >}} Plausible Analytics + [params.analytics.plausible] + domain = "" + + # Cookie 许可配置 + [params.cookieconsent] + enable = true + # 用于 Cookie 许可横幅的文本字符串 + [params.cookieconsent.content] + message = "" + dismiss = "" + link = "" + + # 第三方库文件的 CDN 设置 + [params.cdn] + # CDN 数据文件名称, 默认不启用 + # ("jsdelivr.yml") + # 位于 "themes/CodeIT/assets/data/cdn/" 目录 + # 可以在你的项目下相同路径存放你自己的数据文件: + # "assets/data/cdn/" + data = "" + + # 兼容性设置 + [params.compatibility] + # 是否使用 Polyfill.io 来兼容旧式浏览器 + polyfill = false + # 是否使用 object-fit-images 来兼容旧式浏览器 + objectFit = false + +# Hugo 解析文档的配置 +[markup] + # {{< link "https://gohugo.io/content-management/syntax-highlighting" "语法高亮设置" >}} + [markup.highlight] + codeFences = true + guessSyntax = true + lineNos = true + lineNumbersInTable = true + # false 是必要的设置 + # ({{< link "https://github.com/sunt-programator/CodeIT/issues/158" >}}) + noClasses = false + # Goldmark 是 Hugo 0.60 以来的默认 Markdown 解析库 + [markup.goldmark] + [markup.goldmark.extensions] + definitionList = true + footnote = true + linkify = true + strikethrough = true + table = true + taskList = true + typographer = true + [markup.goldmark.renderer] + # 是否在文档中直接使用 HTML 标签 + unsafe = true + # 目录设置 + [markup.tableOfContents] + startLevel = 2 + endLevel = 6 + +# 作者配置 +[author] + name = "xxxx" + email = "" + link = "" + +# 网站地图配置 +[sitemap] + changefreq = "weekly" + filename = "sitemap.xml" + priority = 0.5 + +# {{< link "https://gohugo.io/content-management/urls#permalinks" "Permalinks 配置" >}} +[Permalinks] + # posts = ":year/:month/:filename" + posts = ":filename" + +# {{< link "https://gohugo.io/about/hugo-and-gdpr/" "隐私信息配置" >}} +[privacy] + # Google Analytics 相关隐私 (被 params.analytics.google 替代) + [privacy.googleAnalytics] + # ... + [privacy.twitter] + enableDNT = true + [privacy.youtube] + privacyEnhanced = true + +# 用于输出 Markdown 格式文档的设置 +[mediaTypes] + [mediaTypes."text/plain"] + suffixes = ["md"] + +# 用于输出 Markdown 格式文档的设置 +[outputFormats.MarkDown] + mediaType = "text/plain" + isPlainText = true + isHTML = false + +# 用于 Hugo 输出文档的设置 +[outputs] + home = ["HTML", "RSS", "JSON"] + page = ["HTML", "MarkDown"] + section = ["HTML", "RSS"] + taxonomy = ["HTML", "RSS"] + taxonomyTerm = ["HTML"] +``` + +{{< admonition >}} +请注意, 本文档其他部分将详细解释其中一些参数. +{{< /admonition >}} + +{{< admonition note "Hugo 的运行环境" >}} +`hugo serve` 的默认运行环境是 `development`, +而 `hugo` 的默认运行环境是 `production`. + +由于本地 `development` 环境的限制, +**评论系统**, **CDN** 和 **fingerprint** 不会在 `development` 环境下启用. + +你可以使用 `hugo serve -e production` 命令来开启这些特性. +{{< /admonition >}} + +{{< admonition tip "关于 CDN 配置的技巧" >}} + +```toml +[params.cdn] + # CDN 数据文件名称, 默认不启用 + # ("jsdelivr.yml") + data = "" +``` + +默认的 CDN 数据文件位于 `themes/CodeIT/assets/data/cdn/` 目录. +可以在你的项目下相同路径存放你自己的数据文件: `assets/data/cdn/`. +{{< /admonition >}} + +{{< admonition tip "关于社交链接配置的技巧" >}} + +你可以直接配置你的社交 ID 来生成一个默认社交链接和图标: + +```toml +[params.social] + Mastodon = "@xxxx" +``` + +生成的社交链接是 `https://mastodon.technology/@xxxx`. + +或者你可以通过一个字典来设置更多的选项: + +```toml +[params.social] + [params.social.Mastodon] + # 排列图标时的权重 (权重越大, 图标的位置越靠后) + weight = 0 + # 你的社交 ID + id = "@xxxx" + # 你的社交链接的前缀 + prefix = "https://mastodon.social/" + # 当鼠标停留在图标上时的提示内容 + title = "Mastodon" +``` + +所有支持的社交链接的默认数据位于 `themes/CodeIT/assets/data/social.yaml`. +你可以参考它来配置你的社交链接. +{{< /admonition >}} + + + +### 3.2 网站图标, 浏览器配置, 网站清单 + +强烈建议你把: + +- apple-touch-icon.png (180x180) +- favicon-32x32.png (32x32) +- favicon-16x16.png (16x16) +- mstile-150x150.png (150x150) +- android-chrome-192x192.png (192x192) +- android-chrome-512x512.png (512x512) + +放在 `/static` 目录. 利用 [https://realfavicongenerator.net/](https://realfavicongenerator.net/) 可以很容易地生成这些文件. + +可以自定义 `browserconfig.xml` 和 `site.webmanifest` 文件来设置 theme-color 和 background-color. + +### 3.3 自定义样式 + +{{< admonition >}} +Hugo **extended** 版本对于自定义样式是必需的. +{{< /admonition >}} + +通过定义自定义 `.scss` 样式文件, **CodeIT** 主题支持可配置的样式. + +包含自定义 `.scss` 样式文件的目录相对于 **你的项目根目录** 的路径为 `assets/css`. + +在 `assets/css/_override.scss` 中, 你可以覆盖 `themes/CodeIT/assets/css/_variables.scss` 中的变量以自定义样式. + +这是一个例子: + +```scss +@import url("https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext"); +$code-font-family: Fira Mono, Source Code Pro, Menlo, Consolas, Monaco, + monospace; +``` + +在 `assets/css/_custom.scss` 中, 你可以添加一些 CSS 样式代码以自定义样式. + +## 4 多语言和 i18n + +**CodeIT** 主题完全兼容 Hugo 的多语言模式, 并且支持在网页上切换语言. + + + +### 4.1 兼容性 {#language-compatibility} + +| 语言 | Hugo 代码 | HTML `lang` 属性 | 主题文档 | Lunr.js 支持 | +| :----------- | :-------: | :--------------: | :---------------------------: | :---------------------------: | +| 英语 | `en` | `en` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| 简体中文 | `zh-cn` | `zh-CN` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): | +| 法语 | `fr` | `fr` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 波兰语 | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| 巴西葡萄牙语 | `pt-br` | `pt-BR` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 意大利语 | `it` | `it` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 西班牙语 | `es` | `es` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 德语 | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 塞尔维亚语 | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): | +| 俄语 | `ru` | `ru` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 罗马尼亚语 | `ro` | `ro` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | +| 越南语 | `vi` | `vi` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): | + +### 4.2 基本配置 + +学习了 [Hugo 如何处理多语言网站](https://gohugo.io/content-management/multilingual) 之后, 请在 [站点配置](#site-configuration) 中定义你的网站语言. + +例如, 一个支持英语, 中文和法语的网站配置: + +```toml +# [en, zh-cn, fr, pl, ...] 设置默认的语言 +defaultContentLanguage = "zh-cn" + +[languages] + [languages.en] + weight = 1 + title = "My New Hugo Site" + languageCode = "en" + languageName = "English" + [[languages.en.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Posts" + url = "/posts/" + title = "" + weight = 1 + [[languages.en.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Tags" + url = "/tags/" + title = "" + weight = 2 + [[languages.en.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Categories" + url = "/categories/" + title = "" + weight = 3 + + [languages.zh-cn] + weight = 2 + title = "我的全新 Hugo 网站" + # 网站语言, 仅在这里 CN 大写 + languageCode = "zh-CN" + languageName = "简体中文" + # 是否包括中日韩文字 + hasCJKLanguage = true + [[languages.zh-cn.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "文章" + url = "/posts/" + title = "" + weight = 1 + [[languages.zh-cn.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "标签" + url = "/tags/" + title = "" + weight = 2 + [[languages.zh-cn.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "分类" + url = "/categories/" + title = "" + weight = 3 + + [languages.fr] + weight = 3 + title = "Mon nouveau site Hugo" + languageCode = "fr" + languageName = "Français" + [[languages.fr.menu.main]] + identifier = "posts" + pre = "" + post = "" + name = "Postes" + url = "/posts/" + title = "" + weight = 1 + [[languages.fr.menu.main]] + identifier = "tags" + pre = "" + post = "" + name = "Balises" + url = "/tags/" + title = "" + weight = 2 + [[languages.fr.menu.main]] + identifier = "categories" + pre = "" + post = "" + name = "Catégories" + url = "/categories/" + title = "" + weight = 3 +``` + +然后, 对于每个新页面, 将语言代码附加到文件名中. + +单个文件 `my-page.md` 需要分为三个文件: + +- 英语: `my-page.en.md` +- 中文: `my-page.zh-cn.md` +- 法语: `my-page.fr.md` + +{{< admonition >}} +请注意, 菜单中仅显示翻译的页面. 它不会替换为默认语言内容. +{{< /admonition >}} + +{{< admonition tip >}} +也可以使用 [文章前置参数](https://gohugo.io/content-management/multilingual#translate-your-content) 来翻译网址. +{{< /admonition >}} + +### 4.3 修改默认的翻译字符串 + +翻译字符串用于在主题中使用的常见默认值. +目前提供[一些语言](#language-compatibility)的翻译, 但你可能自定义其他语言或覆盖默认值. + +要覆盖默认值, 请在你项目的 i18n 目录 `i18n/<languageCode>.toml` 中创建一个新文件，并从 `themes/CodeIT/i18n/en.toml` 中获得提示. + +另外, 由于你的翻译可能会帮助到其他人, 请花点时间通过 [:(fas fa-code-branch fa-fw): 创建一个 PR](https://github.com/sunt-programator/CodeIT/pulls) 来贡献主题翻译, 谢谢! + +## 5 搜索 + +基于 [Lunr.js](https://lunrjs.com/) 或 [algolia](https://www.algolia.com/), **CodeIT** 主题支持搜索功能. + +### 5.1 输出配置 + +为了生成搜索功能所需要的 `index.json`, 请在你的 [网站配置](#site-configuration) 中添加 `JSON` 输出文件类型到 `outputs` 部分的 `home` 字段中. + +```toml +[outputs] + home = ["HTML", "RSS", "JSON"] +``` + +### 5.2 搜索配置 + +基于 Hugo 生成的 `index.json` 文件, 你可以激活搜索功能. + +这是你的 [网站配置](#site-configuration) 中的搜索部分: + +```toml +[params.search] + enable = true + # 搜索引擎的类型 ("lunr", "algolia") + type = "lunr" + # 文章内容最长索引长度 + contentLength = 4000 + # 搜索框的占位提示语 + placeholder = "" + # 最大结果数目 + maxResultLength = 10 + # 结果内容片段长度 + snippetLength = 50 + # 搜索结果中高亮部分的 HTML 标签 + highlightTag = "em" + # 是否在搜索索引中使用基于 baseURL 的绝对路径 + absoluteURL = false + [params.search.algolia] + index = "" + appID = "" + searchKey = "" +``` + +{{< admonition note "怎样选择搜索引擎?" >}} +以下是两种搜索引擎的对比: + +- `lunr`: 简单, 无需同步 `index.json`, 没有 `contentLength` 的限制, 但占用带宽大且性能低 (特别是中文需要一个较大的分词依赖库) +- `algolia`: 高性能并且占用带宽低, 但需要同步 `index.json` 且有 `contentLength` 的限制 + +文章内容被 `h2` 和 `h3` HTML 标签切分来提高查询效果并且基本实现全文搜索. +`contentLength` 用来限制 `h2` 和 `h3` HTML 标签开头的内容部分的最大长度. +{{< /admonition >}} + +{{< admonition tip "关于 algolia 的使用技巧" >}} +你需要上传 `index.json` 到 algolia 来激活搜索功能. 你可以使用浏览器来上传 `index.json` 文件但是一个自动化的脚本可能效果更好. +[Algolia Atomic](https://github.com/chrisdmacrae/atomic-algolia) 是一个不错的选择. +为了兼容 Hugo 的多语言模式, 你需要上传不同语言的 `index.json` 文件到对应的 algolia index, 例如 `zh-cn/index.json` 或 `fr/index.json`... +{{< /admonition >}} diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/language-switch.gif b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/language-switch.gif Binary files differnew file mode 100644 index 0000000..37066df --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-basics/language-switch.gif |
