...
- Home: http://eagle.incubator.apache.org/
- Source code: https://github.com/apache/incubator-eagle/tree/document
- Jekyll: Apache Eagle's document site site http://eagle.incubator.apache.org/) is built upon Jekyll (https://jekyllrb.com/) which is a widely-used static websites and blogs generator program.
- Source code: https://github.com/apache/incubator-eagle/tree/document/website
- Markdown: https://daringfireball.net/projects/markdown/
- Apache SVN Host: Unlike most typical Jekyll web sites, Eagle's website is not hosted on Github Page but Apache SVN server at http://svn.apache.org/viewvc/incubator/eagle/site/
How to Set up Environment
Install Ruby with RVM (http://rvm.io/)
Info Why use RVM instead of native Ruby? http://code.tutsplus.com/articles/why-you-should-use-rvm--net-19529
Code Block language bash curl -sSL https://get.rvm.io | bash -s stable source ~/.profile rvm install ruby
Tips: if you're facing permission issue, try to run commands with "sudo".
Use Ruby and Gem (https://rubygems.org/) to install Jekyll
Info How to install Jeklly? https://jekyllrb.com/docs/installation/
Code Block language bash rvm list rvm use ruby gem install jekyll
Tips: during installation, error "Could not find a valid gem 'jekyll' (>= 0)..." encountered. To solve it, execute "gem sources --add https://ruby.taobao.org/ --remove https://rubygems.org/" before running "gem install jekyll".
Clone Eagle Document Site
Code Block language bash git clone https://github.com/apache/incubator-eagle.git cd incubator-eagle git checkout origin/document -b document
Build and Preview Eagle Document Site (url is http://127.0.0.1:4000/ by default)
Code Block $ cd website $ jekyll serve /Users/hao/.rvm/gems/ruby-2.2.0/gems/execjs-2.6.0/lib/execjs/external_runtime.rb:135: warning: Insecure world writable dir /usr/local in PATH, mode 040777 Configuration file: /Users/hao/Workspace/incubator-eagle/website/_config.yml Source: /Users/hao/Workspace/incubator-eagle/website Destination: /Users/hao/Workspace/incubator-eagle/website/_site Generating... done. Auto-regeneration: enabled for '/Users/hao/Workspace/incubator-eagle/website' Configuration file: /Users/hao/Workspace/incubator-eagle/website/_config.yml Server address: http://127.0.0.1:4000/ Server running... press ctrl-c to stop.
How to Write Document
Info |
---|
Before writing documents, please make sure jekyll server running |
Create a new markdown file like https://raw.githubusercontent.com/apache/incubator-eagle/document/website/introduction.md, where following header on the top:
...
How to Preview
Info Learn more about markdown syntax? https://daringfireball.net/projects/markdown/syntax
Code Block --- layout: doc title: ${document_title, for example "Tutorial"} permalink: ${permalink, for example '/docs/index.html'" --- More Markdown Content Here
Preview new created document by visit http://127.0.0.1:4000/${permalink}, for example, http://127.0.0.1:4000/docs/index.html
Info With jerkell server running, any changes on the markdown files will trigger the jekyll service to rebuild the site automatically with logs like:
Regenerating: 1 file(s) changed at 2016-04-07 13:03:44 ...done in 0.383916 seconds.
Configure new created document into document sidebar in https://github.com/apache/incubator-eagle/blob/document/website/_config.yml#L15 like
Code Block language bash - category: Getting Started links: - title: Introduction url: /docs/index.html
Then the document like will show on the sidebar like http://eagle.incubator.apache.org/docs/ looks.
How to Publish
Info |
---|
The main purpose of this step is to build with "jekyll build" and commit changes in "_site" into "http://svn.apache.org/viewvc/incubator/eagle/site/", then http://eagle.incubator.apache.org/ will automatically serve the changes. |
Clone site from apache svn repository http://svn.apache.org/viewvc/incubator/eagle/site/ into local directory EAGLE_SITE_SVN_DIR for example "eagle-site-svn"
Build as static web site into '_site' directory and commit changes under ${EAGLE_SITE_SVN_DIR} back to apache svn repository
Code Block $ jekyll build Configuration file: /Users/hao/Workspace/incubator-eagle/website/_config.yml Source: /Users/hao/Workspace/incubator-eagle/website Destination: /Users/hao/Workspace/incubator-eagle/website/_site Generating... done.
Commit "_site" content into svn repository
Info How to use SVN? http://svnbook.red-bean.com/ or use GUI tool http://www.smartsvn.com/
- Validate whether the website is updated in http://eagle.incubator.apache.org/docs/
...