Link Search Menu Expand Document
GXL-Groups

安装

使用远端Github主题

在站点的配置文件_config.yml下添加:

1

remote_theme: just-the-docs/just-the-docs

本地安装

1. 通过Reby Gem安装

两种方式:

  1. 通过Terminal输入:

    1

    gem install just-the-docs

  2. 在Gemfile文件中添加下面的内容:

    1

    gem "just-the-docs"

    然后执行bundle install

    注意: 可以通过执行命令:

    1

    bundle config set --local path 'vendor/bundle'

    将安装的依赖项放到项目所在的文件夹下

2. 在项目的_config.yml中设置使用Just the Docs主题 

1

theme: "just-the-docs"

3. 初始化搜索数据,创建一个search-data.json的文件 

1

bundle exec just-the-docs rake search:init

4. 在本地运行Jekyll server 

1

jekyll serve --livereload

--livereload参数选项可以让服务器在更改源文件后自动刷新页面

5. 通过 http://localhost:4000可以预览

配置

通过_config.yml对站点的一些信息进行配置

在assets目录下创建一个iamges文件夹,然后放入设计的$18\times18$的icon图标

然后在配置文件下添加这样一行:

1
2

# Set a path/url to a logo that will be displayed instead of the title
logo: "/assets/images/gxl.png"

配置站点搜索功能 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# Enable or disable the site search
# Supports true (default) or false
search_enabled: true

search:
  # Split pages into sections that can be searched individually
  # Supports 1 - 6, default: 2
  heading_level: 2
  # Maximum amount of previews per search result
  # Default: 3
  previews: 3
  # Maximum amount of words to display before a matched word in the preview
  # Default: 5
  preview_words_before: 5
  # Maximum amount of words to display after a matched word in the preview
  # Default: 10
  preview_words_after: 10
  # Set the search token separator
  # Default: /[\s\-/]+/
  # Example: enable support for hyphenated search words
  tokenizer_separator: /[\s/]+/
  # Display the relative url in search results
  # Supports true (default) or false
  rel_url: true
  # Enable or disable the search button that appears in the bottom right corner of every page
  # Supports true or false (default)
  button: false

添加指向Github主页的链接 

1
2
3
4
5
6
7

# Aux links for the upper right navigation
aux_links:
  "GXL-Groups":
    - "//github.com/gxl-groups/"

# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false

标题链接 

1
2
3
4
5

# Heading anchor links appear on hover over h1-h6 tags in page content
# allowing users to deep link to a particular heading on a page.
#
# Supports true (default) or false
heading_anchors: true

网页页脚内容配置 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Footer content
# appears at the bottom of every page's main content
# Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust markup / liquid-based content.
footer_content: "2022-2025 ShuoYang."

# Footer last edited timestamp
last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
#last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
last_edit_time_format: "%Y年%m月%e日 - %H:%M

# Footer "Edit this page on GitHub" link text
gh_edit_link: true # show or hide edit this page link
gh_edit_link_text: "Edit this page on GitHub."
gh_edit_repository: "https://github.com/gxl-groups/gxl-groups.github.io" # the github URL for your repo
gh_edit_branch: "main" # the branch that your docs is served from
# gh_edit_source: docs # the source that your files originate from
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately

foot_content已经被弃用了,可以通过编辑_includes/footer_custom.html获得更加灵活的配置.只有当页面有一个last_modified_date标记时

站点主题

默认是亮色,可选黑色

1
2

# Color scheme supports "light" (default) and "dark"
color_scheme: dark

google分析 

1
2
3
4

# Google Analytics Tracking (optional)
# e.g, UA-1234567-89
ga_tracking: UA-5555555-55
ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)

文档组织

默认的导航和搜索包括普通页面,可以通过jekyll collections来按语义组织文档

比如,把所有的文档放在doc文件夹下,然后创建doc collection

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# Define Jekyll collections
collections:
  # Define a collection named "docs", its documents reside in the "_docs" directory
  docs:
    permalink: "/:collection/:path/"
    output: true
  envs_tools:
    permalink: "/:collection/:path/"
    output: true

GXL-Groups:
  # Define which collections are used in just-the-docs
  collections:
    # Reference the "docs" collection
    docs:
      # Give the collection a name
      name: Documentation
      # Exclude the collection from the navigation
      # Supports true or false (default)
      nav_exclude: false
      # Exclude the collection from the search
      # Supports true or false (default)
      search_exclude: false
    envs_tools:
      # Give the collection a name
      name: environments_tools
      # Exclude the collection from the navigation
      # Supports true or false (default)
      nav_exclude: false
      # Exclude the collection from the search
      # Supports true or false (default)
      search_exclude: false

比如上面的配置,在项目创建两个文件夹docs和envs_tools,然后创建两个对应的collections,这样可以根据文件的类别分类存.通过nav_exclude 和search_exclude选项来配置,是否显示在导航栏和搜索栏中.