The blog for Impala is generated by a python-based static site generator called Nikola. (This was chosen over another well-known tool, Jekyll, which is Ruby-based.)
The web site is on the asf-site branch of the ASF Impala repo.
$ git clone https://git-wip-us.apache.org/repos/asf/incubator-impala.git impala_website --branch asf-site --single-branch
You will need to install a few python packages to work with Nikola. It‘s up to you whether you want to install the packages directly into your system python environment, or (if you prefer to leave your system environment untouched) into a virtualenv that you can activate whenever you work on the blog, and then deactivate when you’re done.
If you decide to use a virtualenv, you can create it anywhere you have write access (e.g., a sub-directory in your home directory where you may have other virtual environments for other projects), and call it whatever you like. In our example, we're simply calling it blog_env.
Use the virtualenv command to create the virtual environment. A copy of the python executable will be made there, and this is also where any new packages will be installed.
$ virtualenv ~/my_virtualenvs/blog_env New python executable in /home/username/my_virtualenvs/blog_env Installing setuptools, pip, wheel...done.
When you want to work on the blog, start by sourcing the activate script in the bin/ directory within the virtual environment. Once the environment is active, you should see its name added at the beginning of your shell's prompt. The very first time you do this, use the pip command to install all the packages listed in the requirements.txt file.
$ source ~/my_virtualenvs/blog_env/bin/activate (blog_env) $ cd impala_website/nikola_site_generator (blog_env) $ pip install -r requirements.txt
If you decide to forego setting up a virtualenv, and just plan to install the required libraries into your system python, you can just simply run the pip command, but will probably need to use sudo.
Raw articles are stored as markdown files in the nikola_site_generator/posts/ directory, and follow a specific template. Luckily, Nikola provides this template for you, and will even create the empty template in the correct location. (You should probably do this on a new working branch in the repo.)
To start a new post, run the new_post command, after which you will be prompted for a title.
$ nikola new_post Creating New Post ----------------- Title: My New Post Scanning posts........done! [2017-01-10T19:54:32Z] INFO: new_post: Your post's text is at: posts/my-new-post.md
You shoud have an empty dated template now that you can fill in. Note that a “slug” (the generic term for the last term in a permalink) will be auto-generated based upon the title of your post. You can feel free to shorten or edit this as you see fit.
$ cat posts/my-new-post.md <!-- .. title: My New Post .. slug: my-new-post .. date: 2017-01-10 11:54:32 UTC-08:00 .. tags: .. category: .. link: .. description: .. type: text --> Write your post here.
Here's a full sample blog entry.
<!-- .. title: Dream of the Mind's Eye .. slug: dream-of-the-minds-eye .. date: 2016-12-20 11:11:59 UTC-08:00 .. tags: stars, billions .. category: space .. link: .. description: .. author: Carl Saganish .. type: text --> Dream of the mind's eye hydrogen atoms Flatland, not a sunrise but a galaxyrise Orion's sword globular star cluster finite but unbounded muse about. Tingling of the spine citizens of distant epochs, stirred by starlight the sky calls to us Rig Veda encyclopaedia galactica. Birth, Jean-François Champollion citizens of distant epochs shores of the cosmic ocean. Of brilliant syntheses tesseract great turbulent clouds laws of physics, a very small stage in a vast cosmic arena rich in heavy atoms consciousness Flatland, consciousness. Billions upon billions another world at the edge of forever! As a patch of light galaxies. <!-- TEASER_END --> Light years across the centuries kindling the energy hidden in matter a mote of dust suspended in a sunbeam, intelligent beings globular star cluster hearts of the stars stirred by starlight Jean-François Champollion Cambrian explosion cosmic ocean radio telescope Hypatia! Shores of the cosmic ocean Euclid, cosmos Euclid extraplanetary cosmos? Drake Equation courage of our questions descended from astronomers, explorations, trillion laws of physics billions upon billions citizens of distant epochs not a sunrise but a galaxyrise extraordinary claims require extraordinary evidence, the carbon in our apple pies, Apollonius of Perga! Dream of the mind's eye a still more glorious dawn awaits! Kindling the energy hidden in matter dispassionate extraterrestrial observer trillion. Prime number concept of the number one ship of the imagination, hydrogen atoms, Jean-François Champollion laws of physics birth Rig Veda, circumnavigated cosmos star stuff harvesting star light, extraordinary claims require extraordinary evidence, hundreds of thousands. Consciousness brain is the seed of intelligence Sea of Tranquility, paroxysm of global death trillion. Citizens of distant epochs?
Note the special TEASER_END tag after this first paragraph. This is a marker that tells Nikola how much of the the post to preview on the blog index page. If no TEASER_END is specified, the entire post will be visible.
To generate the HTML files for the new article, run the Nikola build command. Your new post will be generated, along with any files that may link to it.
(blog_env) $ nikola build Scanning posts........done! . render_posts:timeline_changes . render_posts:cache/posts/my-new-post.html . render_sources:../blog/posts/my-new-post/index.md . render_archive:../blog/2017/index.html . render_archive:../blog/archive.html . render_indexes:../blog/index.html . render_pages:../blog/posts/impala-blog-coming-soon/index.html . render_pages:../blog/posts/my-new-post/index.html . sitemap:../blog/sitemap.xml . sitemap:../blog/sitemapindex.xml
git status will show which files were created or modified, and so need to be uploaded.
(blog_env) $ git status On branch nikola_site Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: ../blog/2017/index.html modified: ../blog/archive.html modified: ../blog/index.html modified: ../blog/posts/impala-blog-coming-soon/index.html modified: ../blog/sitemap.xml modified: ../blog/sitemapindex.xml Untracked files: (use "git add <file>..." to include in what will be committed) ../blog/posts/my-new-post/ posts/my-new-post.md no changes added to commit (use "git add" and/or "git commit -a")
You can commit these files and push them to gerrit as you would any other code change.
Before you push files gerrit, you may want to see them rendered in a browser first. Nikola includes a basic web server.
(blog_env) $ nikola serve --browser # The default port is 8000
This will open a browser and automatically load the page at 0.0.0.0:8000.
Don‘t forget to deactivate your virtualenv when you’re done working on the blog, by simply callng the deactivate command. This will return you to your system python environment.
(blog_env) $ deactivate $