Open Source Manual Project

A ebook project that demonstrates how to build a open source project from scratch, we will show you some best practices and tools to help your homebrew open source projects from scratch and introduce some background information about open source cultural.

Now we are leverage https://asciidoctor.org[AsciiDoc] to processing the adoc file and generate HTML5 files. The built html https://willemjiang.github.io/open-source-manual/OpenSourceManual.html[here].

link:src/docs/asciidoc/OpenSourceManual.adoc[OpenSourceManual.adoc] is the index file, it includes other files as chapters. Each chapter can also include other adoc file.

You can find more information about how to write the AsciiDoc document by checking out https://asciidoctor.org/docs/asciidoc-writers-guide/[this link].

Usage

Convert the AsciiDoc to HTML5 by invoking the process-resources goal (configured as the default goal):

$ mvn

Open the file target/generated-docs/OpenSourceManual.html in your browser to see the generated HTML file.

output to pdf

Asciidoc PDF need ruby gem env.

$sudo apt-get install ruby
$ gem install asciidoctor-pdf
$ cd src/docs/asciidoc
$ asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-fallback-font OpenSourceManual.adoc

fix chaos Chinese characters.

$ gem install asciidoctor-pdf-cjk-kai_gen_gothic
$ asciidoctor-pdf-cjk-kai_gen_gothic-install  //download font ttf files, if not work, please download them manual.
$ asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicCN OpenSourceManual.asc

maybe you need support download images from remote.

asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicCN -a allow-uri-read OpenSourceManual.adoc

change file /var/lib/gems/2.7.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/exe/asciidoctor-pdf-cjk-kai_gen_gothic-install fonts download url.

url is changed: https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases/tag/v0.1.0-fonts.

if you download manually, please put all ttf files to /var/lib/gems/2.7.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts

the java way ,please go to https://github.com/asciidoctor/asciidoctor-maven-examples/blob/master/asciidoctor-pdf-cjk-example/pom.xml for more details.

custom pdf theme

edit custom file src/docs/asciidoc/resource/themes/style-theme.yml

asciidoctor-pdf --trace -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=style -a allow-uri-read -a pdf-themesdir=resource/themes -a pdf-fontsdir="resource/fonts;GEM_FONTS_DIR" OpenSourceManual.adoc

add another Chinese fonts

copy your fonts (just *.ttf) to target directory. and edit sytle-theme.yml and add this:

SourceCodePro:
  normal: SourceCodePro-Black.ttf
  bold: SourceCodePro-Bold.ttf
  italic: SourceCodePro-It.ttf
  bold_italic: SourceCodePro-BoldIt.ttf

base:
#定义字体
font_family: SourceCodePro

save and quit.

use command :

asciidoctor-pdf --trace -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=style -a allow-uri-read -a pdf-themesdir=resource/themes -a pdf-fontsdir="resource/fonts;YOUR-TARGET-DIR;GEM_FONTS_DIR" OpenSourceManual.adoc