Project: Beam (App Definition and Development / Streaming & Messaging)
File: CONTRIBUTE.md

<!-- 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. --> This guide consists of: - - - - ``` 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 buildcodesamples.sh check-links.sh # links checker package.json ``` If you prefer to experience locally instead of using our gradle commands, this 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 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. 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 ``` 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 ``` For example, you would like to add a new `About` page. First, you need to create a markdown file in `/www/site/content/<LANGUAGEVERSION>/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 for the usage of templates. You can also create a new page with pre-filled frontmatter, for instance, in `/www/site/` run: ``` $ hugo new

``` 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 ``` This section will guide you how to use Hugo shortcodes in Apache Beam website. Please refer to the for more details of usage. To automatically generate table of contents in a markdown file. Simply use: ``` {{< toc >}} ``` 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 >}} {{< /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 >}} {{< /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: . To be consistent, please prefer to use `{{< highlight >}}` syntax instead of ` ``` `, for code-blocks or syntax-highlighters. To apply code highlighting to java, python or go. Use: ``` {{< highlight java >}} // This is java {{< /highlight >}} ``` 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...``` `. To add a class to a single line in mardown. Use: ``` {{< paragraph class="java-language">}} This is an inline markdown text. {{< /paragraph >}} ``` 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. 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 >}} ``` To retrieve a piece of code from Beam project. Usage: ``` {{< codesample "path/to/file" selectedtag >}} ``` Example: ``` {{< codesample "sdks/python/apachebeam/examples/complete/game/userscore.py" extractandsumscore >}} ``` 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

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/casestudy.scss # background-image: url('{{ "images/open-quote.svg" | absURL }}'); ``` This section will briefly let you know the replaced features of Jekyll in terms of writing a new blog post or documentation in Hugo. 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 ``` Redirect from: Fortunately, Hugo supports `redirect_from` with `aliases` in the frontmatter. ``` aliases: /path/example.html ``` 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 or . 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. Relative URLs: `{{ site.baseurl }}` will no longer be used, since Hugo handle the relative or absolute path in the config file. Global variables: The `param` - global variables are placed in the . In Jekyll: ``` {{ site.release_latest }} {{ site.branch_repo }} ``` In Hugo: ``` {{< param release_latest >}} {{< param branch_repo >}} ``` In order to add a new language into Apache Beam website, please follow this guide. You could take a look at an to see how we completely translate the whole website. For more details of syntax, please refer to the . Below is a step-by-step instructions of translating our website to Polish as an example. 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 ``` 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. 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 to understand the structure. Data files Consider the following structure for your data directories `/www/site/data` where `en` and `pl` are your websites 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 }} ``` 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 . Please follow this guide to Please follow this