Always remember to update documentation site via the src-docs
folder and the CHANGELOG.md
in the same PR that contains functional changes. We do this in tandem to prevent our examples from going out of sync with the actual components. In this sense, treat documentation no differently than how you would treat tests.
The complexity of the component should determine how many examples you need to create, and how complex they should be. In general, your examples should demonstrate:
Here are our formatting guidelines for writing documentation:
This component does something
<strong>
tags. Example: <strong>EuiComponent</strong>
Eui
prefix unless you are referencing the generic term. Example: EuiFlyout
vs flyout
<EuiCode>
blocks. Example: <EuiCode>propName</EuiCode>
<EuiCode language="js">propName=true</EuiCode>
<Link to="/component/url><strong>EuiComponent</strong><Link>
In instances where you would like to provide a link to another EUI component
referenced in a given component description or example, take advantage of react-router
,
which is used for routing in EUI docs. Aside from the benefit of shorter path names, react-router
will take the environment into account and provide the correct URL for both development and production locations.
import {
Link,
} from 'react-router-dom';
// ...
Consult the larger <Link to="/guidelines/colors">color guidelines</Link> page
for a better explanation about passing color contrast.
When referring to external sites or resources, use EUI components that take an href
prop, such as EuiLink
.
import {
EuiLink,
} from '/src/components';
// ...
<EuiLink href="https://github.com/elastic/eui/blob/master/src/global_styling/mixins/_shadow.scss">View the Sass code for shadow mixins</EuiLink>.
There are a couple themes to keep in mind when adding snippets:
this.
, but write the snippet like a Function Component.<EuiPopover
id={popoverId}
button={button}
isOpen={isPopoverOpen}
closePopover={closePopover}
anchorPosition="downLeft"
>
<!-- Popover content -->
</EuiPopover>
<EuiLink href="#"><!-- Link text --></EuiLink>
<EuiLink href="#" color="secondary">
<!-- Colored link text -->
</EuiLink>
children
might be.<EuiText color="danger"><!-- Raw HTML content --></EuiText>
<EuiCallOut>
<p><!-- Content --></p>
</EuiCallOut>
<EuiTitle>
<h2><!-- Defaults to medium size. Change the heading level based on your context. --></h2>
</EuiTitle>
<EuiSteps
steps={[
{
title: 'Step 1',
children: <p>Do this first</p>,
},
]}
/>
Any updates to the src/
folder require an entry in the CHANGELOG.md file. Documentation-only changes do not. Here are our guidelines for updating the file:
master
sub-heading of CHANGELOG.md
.此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。