DocsyテーマはHugo Moduleとして取り込まれているため、
hugo serverを実行する際にHugoがこれを解決するにはGoが必要です。
go.modに記載された最小バージョンを満たす任意のバージョンをインストールしてください。
依存関係: Node.js(省略可、本番用CSSパイプライン向け)
hugo serverでサイトをプレビューするだけであれば、Node.jsは不要です。開発モードでは
Docsyが PostCSS の処理をスキップします。ローカルのビルドを、build-site.sh内の
hugo --minifyが実行する本番用CSSパイプライン(autoprefixer/PostCSS)に合わせたい場合にのみ、
Node.js(現行の任意のリリース)が必要です。その場合は、先に
website_and_docsでnpm installを実行してください。
リポジトリにはサイトとドキュメントが含まれています。 変更を加える前に、submoduleを初期化し、必要な依存関係をインストールしてください(以下のコマンドを参照)。サイトに変更を加えるには、website_and_docs ディレクトリで作業してください。変更のライブプレビューを確認するには、サイトのルートディレクトリで hugo serverを実行してください。
% git submodule update --init --recursive
% cd website_and_docs
% hugo server
Fixes #Nを含めてください。ここでは N がこのコミットで修正したイシュー番号です(存在する場合)。
適切なコミットメッセージは次のようになります:
explain commit normatively in one line
Body of commit message is a few lines of text, explaining things
in more detail, possibly giving some background about the issue
being fixed, etc.
The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
72 characters or so. That way `git log` will show things
nicely even when it is indented.
Fixes #141
How to update the Selenium site pages outside of the documentation
The Selenium site is built with Hugo and the Docsy theme.
The site root is the website_and_docs directory. Follow the
contribution mechanics to set up your
environment and preview your changes with hugo server.
Where things live
What
Where
Home page
content/_index.<language>.html
Top level pages (downloads, support, projects, sponsors, etc.)
Some pages have most of their content in the template instead of the Markdown file.
For example, the content of the Downloads page lives in layouts/downloads/list.html.
Markdown versions of documentation pages
Every documentation page is also published as Markdown, at index.md beside its index.html
(for example, /documentation/webdriver/waits/index.md), for AI agents and other tools that read
the site. Each shortcode used in the documentation needs a Markdown template next to its HTML one,
named <shortcode>.markdown.md (the markdown part keeps Hugo from also using it for HTML).
If you add a shortcode to the documentation, add its Markdown template too, and check the page’s
index.md in your preview. build-site.sh fails when a page’s index.md has HTML from a shortcode
that has no Markdown template.
Blog posts
Add a new Markdown file under content/blog/<year>/. Copy the front matter of a recent post
and update the title, linkTitle, date, tags, categories, author, and description.
To use a custom image when the post is shared on social media, add it under
static/images/blog/<year>/ and reference it in the images front matter key.
Translations
The home page and the documentation are translated. Most of the other site pages, including the
blog, are only available in English. When you change text on a translated page, see
Translations in the style guide.
Checking your changes
Site changes are not covered by tests, so preview every page you changed with hugo server.
Every pull request gets a Netlify deploy preview; check it before asking for a review.
2.2 - Contributing to the Selenium documentation
How the Selenium documentation is organized and how to change it
The documentation lives in website_and_docs/content/documentation. Follow the
contribution mechanics to set up your
environment and preview your changes with hugo server.
Structure
Each directory is a section of the documentation, and its _index.<language>.md file is the
section landing page. Each page has one file per language:
<page>.en.md
<page>.ja.md
<page>.pt-br.md
<page>.zh-cn.md
When you add a page, add a file for each language. If you are not translating the content,
copy the English text into the other language files.
Each page starts with front matter like this:
---title:"Sentence capitalization title that describes the page"linkTitle:"Short Title"weight:4description:> One sentence summary of the page.---
weight defines the order of the page in the navigation.
See Capitalization of titles for the
title and linkTitle conventions.
Writing
Keep the prose language independent. Anything specific to a language binding goes inside
code tabs.
Follow the style guide for line length, alerts, and code tabs.
Mark missing content with the alerts described in the
style guide, so others know where help is needed.
Link to other documentation pages with the ref shortcode, e.g.,
[Waits]({{< ref "waits.md" >}}), so broken links fail the build.
Code in the documentation
Code shown in the documentation must come from runnable examples. See
Code examples for how to create them and render them on a page.
How to create runnable code examples and render them in the documentation
We want to be able to run all of our code examples in the CI to ensure that people can copy, paste and
execute everything on the site. So the code lives in the
examples directory,
and the documentation renders it from there.
Each example gets its own test. This keeps the example focused and lets the
documentation point to exactly the lines that matter.
Use the Selenium test pages. Examples need a web page to work against. Use the pages available at
https://www.selenium.dev/selenium/web/ instead of third party sites, which can change or go offline
and break the examples.
Assert the outcome. Each test should have an assertion that verifies the code works as intended,
so that a broken example fails the CI.
Keep the shown code free of test noise. Write the test so that the lines shown in the documentation
are only the Selenium code the reader needs. Assertions and test setup are not shown, unless the
assertion is the clearest way to show the result of the command (e.g., the value returned by a getter).
Run the tests. Run the tests for each language you changed locally, and make sure they pass in the CI.
Each language directory in the
examples directory
has a README with the instructions to run its tests.
These are code examples that are written directly in the Markdown file. Everything from
Creating examples applies: move the code into a test, then render it with
gh-codeblock as described below.
Rendering examples
Once the code is in its own test, it needs to be referenced in the Markdown file with the gh-codeblock
shortcode. For example, the tab in Ruby would look like this:
See Reference GitHub Examples in the style guide for
the complete tabpane syntax. Keep in mind the following:
Show only the relevant lines. The line numbers at the end of the path (#L8-L9) select the lines
that are displayed. Use a single line (#L8) or a range of lines (#L8-L9). Readers can click
“View Complete Code” or “View on GitHub” to see the full test.
One range per code block. A gh-codeblock displays one continuous range of lines.
If the lines you want to show are not next to each other, reorganize the test so they are,
or use one gh-codeblock for each range.
Use text=true. By default, the tabs get formatted for code, so to use markdown or other shortcode
statements (like gh-codeblock) it needs to be declared as text.
For most examples, the tabpane declares the text=true, but if some of the tabs have code examples,
the tabpane cannot specify it, and it must be specified in the tabs that do not need automatic code formatting.
Do not indent the gh-codeblock line. An indented line is rendered as a Markdown code block
instead of running the shortcode.
Keep line numbers up to date. When you add, remove or move lines in an example file, every
gh-codeblock that points to that file below the change needs new line numbers. Search
website_and_docs/content for the file path, and check all languages of the page.
Add the example to all translations. Update the gh-codeblock references in the .ja.md, .pt-br.md
and .zh-cn.md files of the page too.
このドキュメントでは、短くするべき linkTitle にはタイトルケースを使用し、
より長く説明的にできる title には文頭のみ大文字にする形式を使用します。
例えば、linkTitle が Special Heading の場合、title は
The importance of a special heading in documentation のようになります。