website/CONTRIBUTE.md - beam - Git at Google

 <!--
     Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
     regarding copyright ownership.  The ASF licenses this file
     to you under the Apache License, Version 2.0 (the
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
     specific language governing permissions and limitations
     under the License.
 -->

 # Contribution Guide

 This guide consists of:

 - [Project structure](#project-structure)
 - [Configuration walkthrough](#configuration-walkthrough)
 - [How to add a new doc](#how-to-add-a-new-doc)
 - [How to add a new blogpost](#how-to-add-a-new-blogpost)
 - [How to add a new landing page](#how-to-add-a-new-landing-page)
 - [How to write in Hugo way](#how-to-write-in-hugo-way)
   - [Define TableOfContents](#define-tableofcontents)
   - [Language switching](#language-switching)
   - [Code highlighting](#code-highlighting)
   - [Adding class to markdown text](#adding-class-to-markdown-text)
   - [Table](#table)
   - [Github sample](#github-sample)
   - [Others](#others)
   - [How to add relative links to JavaScript or CSS](#how-to-add-relative-links-to-javascript-or-css)
 - [What to be replaced in Jekyll](#what-to-be-replaced-in-jekyll)
 - [Translation guide](#translation-guide)
 - [How to add new case study](#how-to-add-a-new-apache-beam-case-study)
 - [How to add new logo](#how-to-add-a-new-logo-to-case-studies-page)

 ## Project structure

 ```
 www/
 ├── dist                                  # bundle files
 ├── site
 │   ├── archetypes                        # frontmatter template
 │   ├── assets
 │   │         ├── icons                         # svg icons
 │   │         ├── js                            # scripts
 │   │         ├── scss                          # styles
 │   ├── content                           # pages
 │   │   └── en
 │   │       ├── blog
 │   │       ├── case-studies
 │   │       ├── community
 │   │       ├── contribute
 │   │       ├── documentation
 │   │       ├── get-started
 │   │       ├── privacy_policy
 │   │       ├── roadmap
 │   │       └── security
 │   │       └── _index.md
 │   ├── data
 │   ├── layouts                           # content template
 │   ├── static
 │   │   ├── downloads                     # downloaded files
 │   │   └── fonts
 │   │   └── images
 │   └── themes
 │       └── docsy
 ├── build_code_samples.sh
 ├── check-links.sh                        # links checker
 └── package.json
 ```

 ## Configuration walkthrough

 If you prefer to experience locally instead of using our gradle commands, this [Hugo installation](https://gohugo.io/getting-started/installing/) is a good start.

 When we mention the `config file` in this documentation, we mean the Hugo configuration file located at `/www/site/config.toml`.

 Most of the setup are self-explained in the comments. Please refer to the [Hugo documentation](https://gohugo.io/getting-started/configuration/) for more details.

 You should notice at `[params]`, they are considered as global variables. For instance, when you'd like to replace the release latest version, make a change on `release_latest = ""` to replace it everywhere in the project.

 ## How to add a new doc

 Let's start with an example as you'd like to add a new doc named `new-doc` in `/www/site/content/en/documentation/runtime/`. Locate to `/www/site/` and run:

 ```
 $ hugo new documentation/runtime/new-doc.md
 ```

 A markdown file will be created  with pre-filled frontmatter:

 ```
 ---
 title: "New Doc"
 ---
 ```

 Then, put your content below the frontmatter. Do not worry about its layout, since its inside `documentation`, the layout at `/www/site/layouts/documentation/` will be shared with its children.

 **Note**: if you'd like to add a new doc in another language, apart from English version. For example, a new doc inside `pl` directory. Use:

 ```
 $ hugo new -c content/pl documentation/runtime/new-doc.md
 ```

 ## How to add a new blogpost

 To add a new blogpost with pre-filled frontmatter, in `/www/site/` run:

 ```
 $ hugo new blog/my-new-blogpost.md
 ```

 That will create a markdown file `/www/site/content/en/blog/my-new-blogpost.md` with following content:

 ```
 ---
 title: "My New Blogpost"
 date: "2020-04-20T14:02:57+02:00"
 categories:
   - blog
 authors:
   - "Your Name"
 ---
 ```

 Below frontmatter, put your blogpost content. The filename will also serve as URL for your blogpost as `/blog/{filename}`. Don't forget to add `<!--more-->`, which is the delimiter between summary and the main content.

 **Note**: if you'd like to add a new blog in another language, apart from English version. For example, a new blog inside `pl` directory. Use:

 ```
 $ hugo new -c content/pl blog/my-new-blogpost.md
 ```

 ## How to add a new landing page

 For example, you would like to add a new `About` page.

 First, you need to create a markdown file in `/www/site/content/<LANGUAGE_VERSION>/about/_index.md` with following content:

 ```
 ---
 title: "Your page title"
 ---
 ```

 Below frontmatter, put your page content. The filename will also serve as URL for your page as `/about`.

 Second, define your page layout in the `layout` section with the same structure `/www/site/layout/about/{your_template}`. Hugo will help you to pick up the template behind the scene. Please refer to the [Hugo documentation](https://gohugo.io/templates/) for the usage of templates.

 You can also create a new page with pre-filled frontmatter, for instance, in `/www/site/` run:

 ```
 $ hugo new about/_index.md
 ```

 **Note**: if you'd like to add a new page in another language, apart from English version. For example, a new page inside `pl` directory. Use:

 ```
 $ hugo new -c content/pl about/_index.md
 ```

 ## How to write in Hugo way

 This section will guide you how to use Hugo shortcodes in Apache Beam website. Please refer to the [Hugo documentation](https://gohugo.io/content-management/shortcodes/) for more details of usage.

 ### Define TableOfContents

 To automatically generate table of contents in a markdown file. Simply use:

 ```
 {{< toc >}}
 ```

 ### Language switching

 To have a programming language tab switcher, for instance of java, python and go. Use:

 ```
 {{< language-switchers java py go >}}
 ```

 The purpose is to switch languages of codeblocks.

 You can also provide language tabs without the language switcher widget. To do so, place `{{< highlight >}}` shortcodes next to each other, like this:

 ```
 {{< highlight java >}}
 // Java code here...
 {{< /highlight >}}
 {{< highlight py >}}
 # Python code here...
 {{< /highlight >}}
 ```

 Note that the `{{< highlight >}}` blocks should be directly adjacent to each other, without an extra return between them.

 Do NOT do this:

 ```
 {{< highlight java >}}
 // Java code here...
 {{< /highlight >}}

 {{< highlight py >}}
 # Python code here...
 {{< /highlight >}}
 ```

 In some circumstances, the Hugo markdown parser will generate a pair of empty `<p>` tags for the extra return, and that breaks the formatting of the code tabs. TODO: Fix this issue: [Issue 21030](https://github.com/apache/beam/issues/21030).

 ### Code highlighting

 To be consistent, please prefer to use `{{< highlight >}}` syntax instead of ` ``` `, for code-blocks or syntax-highlighters.

 1. To apply code highlighting to java, python or go. Use:

 ```
 {{< highlight java >}}
 // This is java
 {{< /highlight >}}
 ```

 2. To apply code highlighting to a wrapper class

 Usage:

 ```
 {{< highlight class="class-name" >}}
 Write some code here.
 {{< /highlight >}}
 ```

 Render:

 ```
 <div class="class-name">
   <pre>
     <code>
     "Write some code here."
     </code>
   </pre>
 </div>
 ```

 The purpose of adding classes or programming languages (java, py or go) in code highlighting is to activate the language switching feature.
 If you want highlighting for a code block that should *not* be affected by language switching - that is, if you want to a highlight a code block, and you don't want the block to go away when a different language is selected - use ` ``` `. For example: ` ```java // Java code here...``` `.

 ### Adding class to markdown text

 1. To add a class to a single line in mardown. Use:

 ```
 {{< paragraph class="java-language">}}
 This is an inline markdown text.
 {{< /paragraph >}}
 ```

 2. To add a class to multi lines in markdown. Use:

 ```
 {{< paragraph class="java-language" wrap="span">}}
 - This is the first text.
 - This is the second text.
 - This is the third text.
 {{< /paragraph >}}
 ```

 The purpose of adding classes in markdown text is to activate the language switching feature.

 ### Table

 If you would like to use the table markdown syntax but also have bootstrap table styles. Wrap your table markdown inside:

 ```
 {{< table >}}
 A table markdown here.
 {{< /table >}}
 ```

 ### Github sample

 To retrieve a piece of code from Beam project.

 Usage:

 ```
 {{< code_sample "path/to/file" selected_tag >}}
 ```

 Example:

 ```
 {{< code_sample "sdks/python/apache_beam/examples/complete/game/user_score.py" extract_and_sum_score >}}
 ```

 ### Others

 To get released latest version in markdown:

 ```
 {{< param release_latest >}}
 ```

 To get branch of the repository in markdown:

 ```
 {{< param branch_repo >}}
 ```

 To render capability matrix, please take a look at [this example](/www/site/content/en/documentation/runners/capability-matrix/#beam-capability-matrix).

 ### How to add relative links to JavaScript or CSS
 Please take a note that relative links should be added with relative paths to JavaScript or CSS files with using Hugo syntax, so that they are able to form correct absolute links on localhost, staging and production. Examples:
 ```
 /themes/docsy/assets/js/search.js        # var searchPage = "{{ "search/" | absURL }}?q=" + query;
 /assets/js/page-nav.js                   # img.src = "{{ "images/arrow-expandable.svg" | absURL }}";
 /assets/js/copy-to-clipboard.js          # <img src="{{ "images/copy-icon.svg" | absURL }}"/>
 /assets/scss/_case_study.scss            # background-image: url('{{ "images/open-quote.svg" | absURL }}');
 ```

 ## What to be replaced in Jekyll

 This section will briefly let you know the replaced features of Jekyll in terms of writing a new blog post or documentation in Hugo.

 1. Redirect to:

 The `redirect_to` feature will no longer be used since Hugo doesn't support it. You can solve this in Hugo by replacing the external URLs directly in links, instead of using markdown file to be the third-person.

 Currently, there are 3 removed `redirect_to` links which were used in Jekyll:

 ```
 /contribute/project/team/         # https://home.apache.org/phonebook.html?pmc=beam
 /contribute/team/                 # https://home.apache.org/phonebook.html?pmc=beam
 /contribute/design-documents/     # https://cwiki.apache.org/confluence/display/BEAM/Design+Documents
 ```

 2. Redirect from:

 Fortunately, Hugo supports `redirect_from` with `aliases` in the frontmatter.

 ```
 aliases:
   - /path/example.html
 ```

 3. IALs:

 IALs feature is used in Jekyll to add a class to markdown paragraph, `{:.myclass}` as an example. And to show this matter, we use Hugo shortcodes to [add a class to inline texts](#adding-class-to-markdown-text) or [blocks](#code-highlighting).

 4. Filenames of blog posts:

 In Jekyll, filenames included the typical date prefix as part of the filename and it will cause some issues when we'd like to change the date later. Hugo prefers to get rid of them and add date as metadata in frontmatter.

 5. Relative URLs:

 `{{ site.baseurl }}` will no longer be used, since Hugo handle the relative or absolute path in the config file.

 6. Global variables:

 The `param` - global variables are placed in the [config file](#configuration-walkthrough).

 In Jekyll:

 ```
 {{ site.release_latest }}
 {{ site.branch_repo }}
 ```

 In Hugo:

 ```
 {{< param release_latest >}}
 {{< param branch_repo >}}
 ```

 ## Translation guide

 In order to add a new language into Apache Beam website, please follow this guide. You could take a look at an [example branch](https://github.com/PolideaInternal/beam/tree/example/i18n/) to see how we completely translate the whole website.

 For more details of syntax, please refer to the [Hugo documentation](https://gohugo.io/content-management/multilingual/). Below is a step-by-step instructions of translating our website to Polish as an example.

 1. Configuring a new language

 Firstly, we add the following params to our config file `/www/site/config.toml`.

 ```
 [languages.pl]
 contentDir = "content/pl"
 title = "Apache Beam title"
 description = "Apache Beam description"
 languageName = "Polish"
 weight = 2
 ```

 2. Translating markdown contents

 The `www/site/content/pl` directory will be your main workspace of contents here. Therefore, you need to translate all of the markdown files inside `/www/site/content/en` and place them into your workspace. Remember to keep the same project structure for both, since they're sharing the same layouts.

 3. Localizing our strings

 Some of the texts are placed into layouts which are html files, you need to translate all of these phrases inside `www/site/i18n`. Afterwards from our templates, Hugo's `i18n` function does the localization job. Please follow [our example](https://github.com/PolideaInternal/beam/tree/example/i18n/website/www/site/i18n) to understand the structure.

 4. Data files

 Consider the following structure for your data directories `/www/site/data` where `en` and `pl` are your website’s languages’ respective codes.

 ```
 data
   ├── en
   │   └── people.yaml
   └── pl
       └── people.yaml
 ```

 Now from your template:

 ```
 {{ $data := index .Site.Data .Site.Language.Lang }}
 {{ range $data.people }}
   <a href="{{ .url }}">{{ .name }}</a>
 {{ end }}
 ```

 5. Section menus

 Similar to markdown content translation, there are two separated section menus `/www/site/layouts/partials/section-menu` corresponding to your languages. Your job is to take the section menus in `en` directory, translate and place them inside your `pl` directory.

 **Note**: if you get stuck at adding translation, please refer to [our example](https://github.com/PolideaInternal/beam/tree/example/i18n/).

 ## How to add a new Apache Beam case study
 Please follow this guide to [add a new case study](https://github.com/apache/beam/tree/master/website/ADD_CASE_STUDY.md)

 ## How to add a new logo to case studies page
 Please follow this guide to add [a new logo](https://github.com/apache/beam/tree/master/website/ADD_LOGO.md) to the [case studies](https://beam.apache.org/case-studies/) page.
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	# Contribution Guide

	This guide consists of:

	- [Project structure](#project-structure)
	- [Configuration walkthrough](#configuration-walkthrough)
	- [How to add a new doc](#how-to-add-a-new-doc)
	- [How to add a new blogpost](#how-to-add-a-new-blogpost)
	- [How to add a new landing page](#how-to-add-a-new-landing-page)
	- [How to write in Hugo way](#how-to-write-in-hugo-way)
	- [Define TableOfContents](#define-tableofcontents)
	- [Language switching](#language-switching)
	- [Code highlighting](#code-highlighting)
	- [Adding class to markdown text](#adding-class-to-markdown-text)
	- [Table](#table)
	- [Github sample](#github-sample)
	- [Others](#others)
	- [How to add relative links to JavaScript or CSS](#how-to-add-relative-links-to-javascript-or-css)
	- [What to be replaced in Jekyll](#what-to-be-replaced-in-jekyll)
	- [Translation guide](#translation-guide)
	- [How to add new case study](#how-to-add-a-new-apache-beam-case-study)
	- [How to add new logo](#how-to-add-a-new-logo-to-case-studies-page)

	## Project structure

	```
	www/
	├── dist # bundle files
	├── site
	│ ├── archetypes # frontmatter template
	│ ├── assets
	│ │ ├── icons # svg icons
	│ │ ├── js # scripts
	│ │ ├── scss # styles
	│ ├── content # pages
	│ │ └── en
	│ │ ├── blog
	│ │ ├── case-studies
	│ │ ├── community
	│ │ ├── contribute
	│ │ ├── documentation
	│ │ ├── get-started
	│ │ ├── privacy_policy
	│ │ ├── roadmap
	│ │ └── security
	│ │ └── _index.md
	│ ├── data
	│ ├── layouts # content template
	│ ├── static
	│ │ ├── downloads # downloaded files
	│ │ └── fonts
	│ │ └── images
	│ └── themes
	│ └── docsy
	├── build_code_samples.sh
	├── check-links.sh # links checker
	└── package.json
	```

	## Configuration walkthrough

	If you prefer to experience locally instead of using our gradle commands, this [Hugo installation](https://gohugo.io/getting-started/installing/) is a good start.

	When we mention the `config file` in this documentation, we mean the Hugo configuration file located at `/www/site/config.toml`.

	Most of the setup are self-explained in the comments. Please refer to the [Hugo documentation](https://gohugo.io/getting-started/configuration/) for more details.

	You should notice at `[params]`, they are considered as global variables. For instance, when you'd like to replace the release latest version, make a change on `release_latest = ""` to replace it everywhere in the project.

	## How to add a new doc

	Let's start with an example as you'd like to add a new doc named `new-doc` in `/www/site/content/en/documentation/runtime/`. Locate to `/www/site/` and run:

	```
	$ hugo new documentation/runtime/new-doc.md
	```

	A markdown file will be created with pre-filled frontmatter:

	```
	---
	title: "New Doc"
	---
	```

	Then, put your content below the frontmatter. Do not worry about its layout, since its inside `documentation`, the layout at `/www/site/layouts/documentation/` will be shared with its children.

	Note: if you'd like to add a new doc in another language, apart from English version. For example, a new doc inside `pl` directory. Use:

	```
	$ hugo new -c content/pl documentation/runtime/new-doc.md
	```

	## How to add a new blogpost

	To add a new blogpost with pre-filled frontmatter, in `/www/site/` run:

	```
	$ hugo new blog/my-new-blogpost.md
	```

	That will create a markdown file `/www/site/content/en/blog/my-new-blogpost.md` with following content:

	```
	---
	title: "My New Blogpost"
	date: "2020-04-20T14:02:57+02:00"
	categories:
	- blog
	authors:
	- "Your Name"
	---
	```

	Below frontmatter, put your blogpost content. The filename will also serve as URL for your blogpost as `/blog/{filename}`. Don't forget to add `<!--more-->`, which is the delimiter between summary and the main content.

	Note: if you'd like to add a new blog in another language, apart from English version. For example, a new blog inside `pl` directory. Use:

	```
	$ hugo new -c content/pl blog/my-new-blogpost.md
	```

	## How to add a new landing page

	For example, you would like to add a new `About` page.

	First, you need to create a markdown file in `/www/site/content/<LANGUAGE_VERSION>/about/_index.md` with following content:

	```
	---
	title: "Your page title"
	---
	```

	Below frontmatter, put your page content. The filename will also serve as URL for your page as `/about`.

	Second, define your page layout in the `layout` section with the same structure `/www/site/layout/about/{your_template}`. Hugo will help you to pick up the template behind the scene. Please refer to the [Hugo documentation](https://gohugo.io/templates/) for the usage of templates.

	You can also create a new page with pre-filled frontmatter, for instance, in `/www/site/` run:

	```
	$ hugo new about/_index.md
	```

	Note: if you'd like to add a new page in another language, apart from English version. For example, a new page inside `pl` directory. Use:

	```
	$ hugo new -c content/pl about/_index.md
	```

	## How to write in Hugo way

	This section will guide you how to use Hugo shortcodes in Apache Beam website. Please refer to the [Hugo documentation](https://gohugo.io/content-management/shortcodes/) for more details of usage.

	### Define TableOfContents

	To automatically generate table of contents in a markdown file. Simply use:

	```
	{{< toc >}}
	```

	### Language switching

	To have a programming language tab switcher, for instance of java, python and go. Use:

	```
	{{< language-switchers java py go >}}
	```

	The purpose is to switch languages of codeblocks.

	You can also provide language tabs without the language switcher widget. To do so, place `{{< highlight >}}` shortcodes next to each other, like this:

	```
	{{< highlight java >}}
	// Java code here...
	{{< /highlight >}}
	{{< highlight py >}}
	# Python code here...
	{{< /highlight >}}
	```

	Note that the `{{< highlight >}}` blocks should be directly adjacent to each other, without an extra return between them.

	Do NOT do this:

	```
	{{< highlight java >}}
	// Java code here...
	{{< /highlight >}}

	{{< highlight py >}}
	# Python code here...
	{{< /highlight >}}
	```

	In some circumstances, the Hugo markdown parser will generate a pair of empty `<p>` tags for the extra return, and that breaks the formatting of the code tabs. TODO: Fix this issue: [Issue 21030](https://github.com/apache/beam/issues/21030).

	### Code highlighting

	To be consistent, please prefer to use `{{< highlight >}}` syntax instead of ` ``` `, for code-blocks or syntax-highlighters.

	1. To apply code highlighting to java, python or go. Use:

	```
	{{< highlight java >}}
	// This is java
	{{< /highlight >}}
	```

	2. To apply code highlighting to a wrapper class

	Usage:

	```
	{{< highlight class="class-name" >}}
	Write some code here.
	{{< /highlight >}}
	```

	Render:

	```
	<div class="class-name">
	<pre>
	<code>
	"Write some code here."
	</code>
	</pre>
	</div>
	```

	The purpose of adding classes or programming languages (java, py or go) in code highlighting is to activate the language switching feature.
	If you want highlighting for a code block that should not be affected by language switching - that is, if you want to a highlight a code block, and you don't want the block to go away when a different language is selected - use ` ``` `. For example: ` ```java // Java code here...``` `.

	### Adding class to markdown text

	1. To add a class to a single line in mardown. Use:

	```
	{{< paragraph class="java-language">}}
	This is an inline markdown text.
	{{< /paragraph >}}
	```

	2. To add a class to multi lines in markdown. Use:

	```
	{{< paragraph class="java-language" wrap="span">}}
	- This is the first text.
	- This is the second text.
	- This is the third text.
	{{< /paragraph >}}
	```

	The purpose of adding classes in markdown text is to activate the language switching feature.

	### Table

	If you would like to use the table markdown syntax but also have bootstrap table styles. Wrap your table markdown inside:

	```
	{{< table >}}
	A table markdown here.
	{{< /table >}}
	```

	### Github sample

	To retrieve a piece of code from Beam project.

	Usage:

	```
	{{< code_sample "path/to/file" selected_tag >}}
	```

	Example:

	```
	{{< code_sample "sdks/python/apache_beam/examples/complete/game/user_score.py" extract_and_sum_score >}}
	```

	### Others

	To get released latest version in markdown:

	```
	{{< param release_latest >}}
	```

	To get branch of the repository in markdown:

	```
	{{< param branch_repo >}}
	```

	To render capability matrix, please take a look at [this example](/www/site/content/en/documentation/runners/capability-matrix/#beam-capability-matrix).

	### How to add relative links to JavaScript or CSS
	Please take a note that relative links should be added with relative paths to JavaScript or CSS files with using Hugo syntax, so that they are able to form correct absolute links on localhost, staging and production. Examples:
	```
	/themes/docsy/assets/js/search.js # var searchPage = "{{ "search/" \| absURL }}?q=" + query;
	/assets/js/page-nav.js # img.src = "{{ "images/arrow-expandable.svg" \| absURL }}";
	/assets/js/copy-to-clipboard.js # <img src="{{ "images/copy-icon.svg" \| absURL }}"/>
	/assets/scss/_case_study.scss # background-image: url('{{ "images/open-quote.svg" \| absURL }}');
	```

	## What to be replaced in Jekyll

	This section will briefly let you know the replaced features of Jekyll in terms of writing a new blog post or documentation in Hugo.

	1. Redirect to:

	The `redirect_to` feature will no longer be used since Hugo doesn't support it. You can solve this in Hugo by replacing the external URLs directly in links, instead of using markdown file to be the third-person.

	Currently, there are 3 removed `redirect_to` links which were used in Jekyll:

	```
	/contribute/project/team/ # https://home.apache.org/phonebook.html?pmc=beam
	/contribute/team/ # https://home.apache.org/phonebook.html?pmc=beam
	/contribute/design-documents/ # https://cwiki.apache.org/confluence/display/BEAM/Design+Documents
	```

	2. Redirect from:

	Fortunately, Hugo supports `redirect_from` with `aliases` in the frontmatter.

	```
	aliases:
	- /path/example.html
	```

	3. IALs:

	IALs feature is used in Jekyll to add a class to markdown paragraph, `{:.myclass}` as an example. And to show this matter, we use Hugo shortcodes to [add a class to inline texts](#adding-class-to-markdown-text) or [blocks](#code-highlighting).

	4. Filenames of blog posts:

	In Jekyll, filenames included the typical date prefix as part of the filename and it will cause some issues when we'd like to change the date later. Hugo prefers to get rid of them and add date as metadata in frontmatter.

	5. Relative URLs:

	`{{ site.baseurl }}` will no longer be used, since Hugo handle the relative or absolute path in the config file.

	6. Global variables:

	The `param` - global variables are placed in the [config file](#configuration-walkthrough).

	In Jekyll:

	```
	{{ site.release_latest }}
	{{ site.branch_repo }}
	```

	In Hugo:

	```
	{{< param release_latest >}}
	{{< param branch_repo >}}
	```

	## Translation guide

	In order to add a new language into Apache Beam website, please follow this guide. You could take a look at an [example branch](https://github.com/PolideaInternal/beam/tree/example/i18n/) to see how we completely translate the whole website.

	For more details of syntax, please refer to the [Hugo documentation](https://gohugo.io/content-management/multilingual/). Below is a step-by-step instructions of translating our website to Polish as an example.

	1. Configuring a new language

	Firstly, we add the following params to our config file `/www/site/config.toml`.

	```
	[languages.pl]
	contentDir = "content/pl"
	title = "Apache Beam title"
	description = "Apache Beam description"
	languageName = "Polish"
	weight = 2
	```

	2. Translating markdown contents

	The `www/site/content/pl` directory will be your main workspace of contents here. Therefore, you need to translate all of the markdown files inside `/www/site/content/en` and place them into your workspace. Remember to keep the same project structure for both, since they're sharing the same layouts.

	3. Localizing our strings

	Some of the texts are placed into layouts which are html files, you need to translate all of these phrases inside `www/site/i18n`. Afterwards from our templates, Hugo's `i18n` function does the localization job. Please follow [our example](https://github.com/PolideaInternal/beam/tree/example/i18n/website/www/site/i18n) to understand the structure.

	4. Data files

	Consider the following structure for your data directories `/www/site/data` where `en` and `pl` are your website’s languages’ respective codes.

	```
	data
	├── en
	│ └── people.yaml
	└── pl
	└── people.yaml
	```

	Now from your template:

	```
	{{ $data := index .Site.Data .Site.Language.Lang }}
	{{ range $data.people }}
	<a href="{{ .url }}">{{ .name }}</a>
	{{ end }}
	```

	5. Section menus

	Similar to markdown content translation, there are two separated section menus `/www/site/layouts/partials/section-menu` corresponding to your languages. Your job is to take the section menus in `en` directory, translate and place them inside your `pl` directory.

	Note: if you get stuck at adding translation, please refer to [our example](https://github.com/PolideaInternal/beam/tree/example/i18n/).

	## How to add a new Apache Beam case study
	Please follow this guide to [add a new case study](https://github.com/apache/beam/tree/master/website/ADD_CASE_STUDY.md)

	## How to add a new logo to case studies page
	Please follow this guide to add [a new logo](https://github.com/apache/beam/tree/master/website/ADD_LOGO.md) to the [case studies](https://beam.apache.org/case-studies/) page.