Gitbook Action

This action builds and publishes a gitbook to github pages and other pages. Click here for more information.

GitHub | MarketPlace | Page | Community

How to Use

STEP1 Add Action

Add .github/workflows/gitbook-action.ymlin your repo, with following content.

name: 'Gitbook Action Build'
on:
  push:
    branches:
      - master  # trigger branch
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout action
      uses: actions/[email protected]
    - name: Gitbook Action                    # https://github.com/ZanderZhao/gitbook-action/releases
      uses: ZanderZhao/[email protected].2.4  # -> or ZanderZhao/[email protected] not use master click above, use latest please 
      with:                                   #    or fork this repo and use YourName/[email protected]
        token: ${{ secrets.PERSONAL_TOKEN }}  # -> remember add this in settings/secrets as following

Detailed step | Official introduction

STEP2 Generate Token and add to Secrets

Create token from https://github.com/settings/tokens

  • choose repo
  • click Generate token

Detailed step | Official introduction

Add your token to https://github.com/ yourname/yourrepo /settings/secrets

  • Name: PERSONAL_TOKEN
  • Value: which you get before

Detail step | Official introduction

STEP3 Choose options

  • Set Default Above source branch is master, and the target branch is gh-pages. If gh-pages does not exist, it will be created automatically.
  • The following are options.

Option

For global

  • git_name:

    • description: ' If git name is different with github, please add'
    • default: GITHUB_ACTOR
  • time_zone:

For Source Repo

  • source_repo:

    • description: 'Default this GITHUB_REPOSITORY, if not please add like username/reponame '
  • source_token:

    • description: 'Default token, if not please add (clone)'
  • source_git_name:

    • description: 'Default git_name, if not please add'
  • source_hub:
  • description: 'default is github.com,can be gitlib.com gitee.com ...'

  • default: 'github.com'

  • source_branch:

    • description: 'Default master'

    • default: 'master'

  • source_dir:

    • description: 'Where gitbook source. Default is root, if not add like mydir, instead of /mydir or mydir/'

    • default: '/'

  • source_edit_time:

    • description: 'Default false, if plugins need last edit time, set true'

    • default: false

  • source_file_without_prefix:

    • description: 'Default true, if you want to ignore file without prefix please set false'

    • default: true

For Publish Repo

  • publish_repo:

    • description: 'Default this GITHUB_REPOSITORY, if not please add like username/reponame'
  • publish_token:

    • description: 'Default token, if not please add (clone push)'
  • publish_git_name:

    • description: 'Default git_name, if not please add'
  • publish_git_email:

    • description: 'Default git_email, if not please add'
  • publish_commit_message:

    • description: 'Default Updated by gitbook-action and time, can use last commit message'
    • Tip: can set github.event.head_commit.message as last commit message example1
  • publish_hub:
  • description: 'Default is github.com,can be gitlib.com gitee.com ...'

  • default: 'github.com'

  • publish_branch:

    • description: 'Defaule is gh-pages, auto create'

    • default: 'gh-pages'

  • publish_dir:

    • description: 'Default is root, if not add like docs ...'

    • default: '/'

  • publish_commit_history:

    • description: 'set false will only one commit at publish_repo'

    • default: true

  • publish_cname:

    • description: 'Default null'

    • default: 'null'

  • publish_nojekyll:

    • description: 'Default false, if set true, it will add .nojekyll for publish'

    • default: 'false'

  • publish_push_force:

    • description: 'Default false. Set true will enable git push force'

    • default: false

  • publish_remove_last_build:

    • description: 'Default true. Set false not remove last build but rewrite same file'

    • default: true

For Gitbook Setting

  • gitbook_cli_version:

    • description: 'Default is 2.3.2'

    • default: '2.3.2'

  • gitbook_version:

    • description: 'Default is 3.2.3'

    • default: '3.2.3'

  • gitbook_pdf:

    • description: 'Set true will generate pdf file'

    • default: false

  • gitbook_pdf_dir:

    • description: 'Where the pdf to put. Default mybook, can change / for root, or myebook'

    • default: 'mybook'

  • gitbook_pdf_name:

    • description: 'The name of your pdf. Default ebook'

    • default: 'ebook'

  • gitbook_epub:

    • description: 'Set true will generate epub file'

    • default: false

  • gitbook_epub_dir:

    • description: ''

    • default: 'mybook'

  • gitbook_epub_name:

    • description: ''

    • default: 'ebook'

  • gitbook_mobi:

    • description: 'Set true will generate mobi file'

    • default: false

  • gitbook_mobi_dir:

    • description: ''

    • default: 'mybook'

  • gitbook_mobi_name:

    • description: ''
    • default: 'ebook'
  • font_install

    • description: 'Install font for pdf, Not install any font, maybe affect the pdf/mobi/epub, can add font_install at book.json'
    • example: sudo apt-get install fonts-noto-cjkorsudo apt-get install ttf-mscorefonts-installer,use sudo install for global.
  • not_clean

    • description: 'Default false. Set true will not remove working file when the workflow finish, if you set cache'
  • prepare_install

    • description: 'Some install for prepare, such as dependency, golbal setting'
    • example: npm i --unsafe-perm -g [email protected],install specific svgexport version for converting svg.

For other repo

For Source2 repo

  • source2_repo:

    • description: 'Default null, if use please add like username/reponame, (same with source will replace, different will mix)'
    • default: 'null'
  • source2_git_name:

    • description: 'Default git_name, if not please add'
  • source2_token:

    • description: 'Default token, if not please add (clone)'
  • source2_hub:

    • description: ''

    • default: 'github.com'

  • source2_branch:

    • description: ''

    • default: 'master'

  • source2_dir:

    • description: ''

    • default: '/'

  • source2_edit_time:

    • description: 'Default false if plugins need last edit time, set true'

    • default: false

  • source2_file_without_prefix:

    • description: 'Default true, if you want to ignore file without prefix please set false'

    • default: true

For Publish2 repo

  • publish2_repo:

    • description: 'Default null, if use please add like username/reponame'
    • default: 'null'
  • publish2_git_name:

    • description: 'Default git_name, if not please add'
  • publish2_token:

    • description: 'Default token, if not please add (clone push)' required: 'false'
  • publish2_git_email:

    • description: 'Default git_email, if not please add'
  • publish2_commit_message:

    • description: 'Default Updated by gitbook-action and time'
  • publish2_hub:

    • description: ''

    • default: 'github.com'

  • publish2_branch:

    • description: 'Default gh-pages'

    • default: 'gh-pages'

  • publish2_dir:

    • description: ''

    • default: '/'

  • publish2_cname:

    • description: 'Default null'

    • default: 'null'

  • publish2_push_force:

    • description: 'Default false. Set true will enable git push force'

    • default: false

  • publish_remove_last_build:

    • description: 'Default true. Set false not remove last build but rewrite same file'

    • default: true

  • publish2_commit_history:

    • description: 'set false will only one commit at publish2_repo'

    • default: true

  • publish2_nojekyll:

    • description: 'Default false, if set true, it will add .nojekyll for publish2'

    • default: 'false'

For Publish3 repo

  • publish3_git_name:

    • description: 'Default git_name, if not please add'
  • publish3_token:

    • description: 'Default token, if not please add (clone push)'
  • publish3_git_email:

    • description: 'Default git_email, if not please add'
  • publish3_commit_message:

    • description: 'Default Updated by gitbook-action and time'
  • publish3_hub:

    • description: ''

    • default: 'github.com'

  • publish3_repo:

    • description: 'Default null, if use please add like username/reponame'

    • default: 'null'

  • publish3_branch:

    • description: 'Default gh-pages'

    • default: 'gh-pages'

  • publish3_dir:

    • description: 'Default root'

    • default: '/'

  • publish3_cname:

    • description: 'Default null'

    • default: 'null'

  • publish3_push_force:

    • description: 'Default false. Set true will enable git push force'

    • default: false

  • publish_remove_last_build:

    • description: 'Default true. Set false not remove last build but rewrite same file'

    • default: true

  • publish3_commit_history:

    • description: 'set false will only one commit at publish3_repo'
    • default: true
  • publish3_nojekyll:

    • description: 'Default false, if set true, it will add .nojekyll for publish3'

    • default: 'false'

Example

name: 'Gitbook-Action'

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout action
      uses: actions/[email protected]

    # example1--> https://ZanderZhao.github.io/gitbook-action
    - name: Gitbook Action
      uses: zanderzhao/[email protected].2.4 # https://github.com/ZanderZhao/gitbook-action/releases 
      with:                                # Just example, click above, use latest please 
        token: ${{ secrets.PERSONAL_TOKEN }}
        time_zone: Asia/Shanghai   # set time zone
        source_dir: source         # clone from source
        source_edit_time: true     # source time
        publish_commit_message: ${{ github.event.head_commit.message }}  # use last commit message

    # example2--> https://ZanderZhao.github.io/gitbook-action/gitbook-docs
    - name: Gitbook Action
      uses: zanderzhao/[email protected].2.4
      with:
        token: ${{ secrets.PERSONAL_TOKEN }} 
        time_zone: Asia/Shanghai
        source_repo: GitbookIO/gitbook    # clone from https://github.com/GitbookIO/gitbook.git
        source_branch: master             # clone source master
        source_dir: docs                  # gitbook-sorce at dir:docs
        publish_dir: gitbook-docs            # publish for this repo dir:gitbook-docs
        publish2_repo: gitbook-org/gitbook   # publish for another repo dir default root

FAQ

ERROR

WARNING

Q&A

  • About last edit time

    • How to keep the last edit time ?
      • Add source_edit_time: true
  • About CNAME

  • About PDF/EPUB/MOBI

    • How to build pdf ?
      • Add gitbook_pdf: true
        • You can choose gitbook_pdf_dir and gitbook_pdf_name
        • Detail
      • Why the font format is wrong ?
        • You need install font, add font_install
        • example: font_install: sudo apt-get install fonts-noto-cjkorfont_install: sudo apt-get install ttf-mscorefonts-installer,use sudo install for global.
  • About source_repo

        source_repo: GitbookIO/gitbook
        source_branch: master
        source_dir: docs
  • About publish_repo
    • publish_repo is the file gitbook build push to
    • you can set publish_repopublish_branchandpublish_dir
    • This action only change the file in publish_dir
  • About work
    • Pull docker from docker
      • In which Gitbook and Tools has installed
    • Clone from publish
      • If exists publish2 and publish3
        • Then clone publish2 and publish3
        • Mix publish, publish2 and publish3 together
    • Build
      • If exists plugins
        • install plugins
      • if need pdf
        • if set font
          • install font if you set before
        • build pdf
    • Publish
      • Publish to publish_repo
      • If exists publish2 or publish3, then publish
    • Clean
      • It will clean all things, If you need cache can set false, and you can find detail in OPTION above

Community

Gitter

External links

results matching ""

    No results matching ""