Rakuten Engineering Blog Sources

Quick Start

Running locally

Install Hugo.

Please make sure you install the extended version of Hugo. The Homebrew installer for Mac should install the extended version, and the same is probably true for other package manager. If you want to verify which version you are using, run:
```
> hugo version
```
You should see output like:
```
Hugo Static Site Generator v0.78.2/extended darwin/amd64 BuildDate: unknown
```
Fork & Clone this repository
Run the local server with:
```
> hugo server
```
Browse to the local server URL with your favourite browser.

Creating a new blog post

Open a new git branch for your post:

> git checkout -b post/docking-with-docker

Generate new post markdown file:
```
> hugo new post/docking-with-docker.md
```
Edit the post with your favourite text editor.
Run hugo server -D to test how the draft post looks locally.
When you think the post is ready, submit a pull request with post. Please keep the draft flag in the Front Matter (YAML header on top of your file) as true - the administrator will remove the draft flag when your post pull-request is merged and published.

Generating site HTML and deploying to GitHub Pages

Run the shell script ./deploy to re-render the blog and deploy everything to GitHub pages.

How To:

Add a new author profile

Create a folder for yourself under ./content/authors/YOUR_NAME
Add an avatar image

Add an _index.md file, for example

title: Your Name
bio: |
   Your Bio
avatar: /authors/YOUR_NAME/YOUR_AVATAR.png
social:
- title: github
   url: https://github.com/YOUR_GITHUB
   # other social links

See the author partial for details on how it will be rendered

Add more languages to syntax highlighting

To reduce bundle download size, the syntax highlighting script is currently not configured to support all languages. If you find that you need a new language that is not supported, you can add it by upgrading the CSS and JS assets used by Prism for syntax highlighting:

Open assets/css/prism.css or assets/js/prism.js and look at the header. It should contain the download link that was used to generate this file.
Open the download link in your browser.
Put in a check mark for the language (or languages) you want to add.
Click the download CSS button and copy the downloaded CSS file over assets/css/prism.css.
Click the download JS button and copy the downloaded JavaScript file over assets/js/prism.js.
Restart the Hugo server and reload everything in your browser (Cmd+Shift-R on Mac and Ctrl-Shift-R on Windows or Linux) to make sure your cache is refreshed.

Prepare PDF for PR review

We use pandoc, for example via docker

docker run --rm --volume "`pwd`:/data" --user `id -u`:`id -g` pandoc/latex path/to/source.md -o output.pdf --pdf-engine=xelatex

apparition47 / engineering-blog