Quick Start

Installation

Manual Download

Download 👉 Everkm Publish command line tool, unzip it, and put the executable everkm-publish into the search directory set by the PATH variable to run it from the command line.

Mac Brew Installation

brew install everkm/tap/everkm-publish

Npm / Pnpm Installation

pnpm add everkm-publish

Usually used for Customized templates development.

Create Workspace

# Create a workspace in the current directory
everkm-publish create <base name>

Common Parameters:

• --theme optional. Specify the style name. Default is yilog.

Launch local preview

1. Launch preview

   # Switch to the Base directory
   cd <base dir>
   
   # Start the preview environment
   everkm-publish serve --theme <your theme>
   

   Open http://localhost:9081 (default listening address) in your browser to preview.

2. Edit the Markdown file in the <base>/content/post/ directory.

3. Export static file

   everkm-publish serve --theme <your theme> --export
   

Directory Structure

.
├── Makefile            # Auxiliary command management, optional
├── content             # Data directory
│   └── post            # Root directory of content
│       ├── _page       # Project data, directories or files starting with `_` will be ignored by the `posts` function
│       ├── docs        # Project data
│       └── guide       # Project data
├── dist                # Usually used as the release directory
├── everkm-theme.yaml   # Template development, template configuration file 
├── everkm.yaml         # Project configuration file
├── package.json        # Template development, JavaScript dependencies, optional
├── webpack.config.js   # Template development, optional
├── src                 # Template development directory
│   ├── assets
│   └── templates       # Template files
│       ├── en_US.i18n.md # Language pack
│       ├── detail.html # Template detail page
│       └── index.html  # Template homepage
├── theme               # Template installation directory
│   ├── dev             # Pre-release directory for developing templates
│   └── yilog           # Other installed templates

Workspace Configuration File

File name: everkm.yaml

Sets the structure, templates and parameters of the rendering, with a higher priority than [everkm-theme.yaml](custom-template#Template profile).

cfg:
  site:
    timezone: Asia/Chongqing
    name: Everkm
    description: Ever Knowledge Management
    keywords: kms, km

sitemap:
  channel_name: "{{t(text='Home')}}"
  children:
    - path: blog/
      channel_name: "{{t(text='Blog')}}"
      channel_path: blog/
      qs:
        dir: /blog/
        __tpl: /list.html
        no_dir: true
        category_url_base: /blog/category/
        page_size: 10
    - path: changelog.html
      channel_name: "{{t(text='Changelog')}}"
      qs:
        __tpl: /details.html
        no_dir: true
        no_time: true

map_url:
  - dir: /blog/**
    url: /blog/{{year}}/{{slug}}.html
  - dir: /docs/**
    url: /docs/{{slug}}.html

cfg field

• cfg Workspace configuration, available in the template via global variable __cfg.
• cfg.timezone Default workspace timezone, default value `Asia/Chongqing
• cfg.default_lang Default language translation environment, default value `en_US

The map_url field.

• map_url is used to generate a URL from a file path.
• map_url.dir Path wildcards
• map_url.url The corresponding URL Path. The following placeholders are supported, wrapped in {{}}.
  1. slug File Slug
  2. year Year of document creation
  3. month Month of document creation
  4. day Day of document creation

sitemap field

• sitemap overrides the sitemap configuration in everkm-theme.yaml.
• The sitemap sets the site structure. All field values support template syntax.
• sitemap.path Url Path wildcard, defaults to / when omitted. When ending with /, it means all files in the directory, but not descendants. E.g. blog/ is equivalent to blog/*.
• sitemap.channel_name channel name, used for breadcrumb navigation, ignore this field if omitted.
• sitemap.channel_path channel URL fragment, used for breadcrumb navigation, use path attribute when omitting, if there is wildcard, it will report error.
• sitemap.qs Contextual parameter for rendering templates, get it from global variable __qs.
• sitemap.qs.__tpl Path to the template to be used by default.
• sitemap.qs.* Other customization parameters.
• sitemap.children[] Child path, same type as sitemap.

Preview / Export

Render Export All Pages

everkm-publish serve --export

everkm-publish will start at the entry address, grab its content, save it as a file by URL Path section, and follow other links to the grabbed content. If it meets the specified rules, it will continue to capture the content until the export is complete. In addition to exporting page content, it will also include images, audio, video, and other document attachments referenced in the article. Uncited resources will not be exported.

Special directories

If you need to publish some unreferenced files together, you need to put them into the following special directory.

1. __assets: Copy to the static resource assets directory when publishing. This is mainly for resource files attached to pages.
2. __public: Copy to the content page directory when publishing.

Note: When the target file exists, it will be overwritten.

Detailed parameters

Preview / Export

Usage: everkm-publish serve [OPTIONS]

Options:
      --work-dir <WORK_DIR>
          Working directory
          
          [env: EVERKM_WORK_DIR=]
          [default: ./]

      --dev-dir <DEV_DIR>
          Development directory
          
          Priority over work_dir
          
          [env: EVERKM_DEV_DIR=]

      --dist-dir <DIST_DIR>
          Export directory
          
          [env: EVERKM_DIST_DIR=]

      --theme <THEME>
          Name of theme
          
          [env: EVERKM_THEME=]
          [default: dev]

      --cdn-prefix <CDN_PREFIX>
          CDN's prefix of assets
          
          [env: EVERKM_CDN_PREFIX=]

      --lang <LANG>
          Language code
          
          [env: EVERKM_LANG=]

      --base-prefix <BASE_PREFIX>
          Context base of url
          
          [env: EVERKM_BASE_PREFIX=]
          [default: ]

      --listen <LISTEN>
          Listening address
          
          [env: EVERKM_LISTEN=]
          [default: 127.0.0.1:9081]

  -e, --export
          As export mode

      --start-urls <START_URLS>
          A list of exported entry addresses. Multiple are separated by
          spaces.
          
          Default:  `/index.html`
          
          [env: EVERKM_START_URLS=]

      --stop-urls <STOP_URLS>
          A list of address prefixes to ignore. Multiple are separated by
          spaces
          
          [env: EVERKM_STOP_URLS=]

  -h, --help
          Print help (see a summary with '-h')