ContextQMD
Back to Spacy

Styleguide

website/docs/styleguide.mdx

4.0.0.dev1018.2 KB
Original Source

The spacy.io website is implemented using Gatsby with Remark and MDX. This allows authoring content in straightforward Markdown without the usual limitations. Standard elements can be overwritten with powerful React components and wherever Markdown syntax isn't enough, JSX components can be used.

Contributing to the site

The docs can always use another example or more detail, and they should always be up to date and not misleading. We always appreciate a pull request. To quickly find the correct file to edit, simply click on the "Suggest edits" button at the bottom of a page.

For more details on editing the site locally, see the installation instructions and markdown reference below.

Logo {id="logo",source="website/src/images/logo.svg"}

If you would like to use the spaCy logo on your site, please get in touch and ask us first. However, if you want to show support and tell others that your project is using spaCy, you can grab one of our spaCy badges.

<Logos />

Colors {id="colors"}

<Colors />

Patterns

<Patterns />

Typography {id="typography"}

Markdown

markdown
## Headline 2

## Headline 2 {id="some_id"}

## Headline 2 {id="some_id" tag="method"}

JSX

jsx
<H2>Headline 2</H2>
<H2 id="some_id">Headline 2</H2>
<H2 id="some_id" tag="method">Headline 2</H2>

Headlines are set in HK Grotesk by Hanken Design. All other body text and code uses the best-matching default system font to provide a "native" reading experience. All code uses the JetBrains Mono typeface by JetBrains.

<Infobox title="Important note" variant="warning">

Level 2 headings are automatically wrapped in <section> elements at compile time, using a custom Markdown transformer. This makes it easier to highlight the section that's currently in the viewpoint in the sidebar menu.

</Infobox> <div> <H2>Headline 2</H2> <H3>Headline 3</H3> <H4>Headline 4</H4> <H5>Headline 5</H5> <Label>Label</Label> </div>

The following optional attributes can be set on the headline to modify it. For example, to add a tag for the documented type or mark features that have been introduced in a specific version or require statistical models to be loaded. Tags are also available as standalone <Tag /> components.

ArgumentExampleResult
tag{tag="method"}<Tag>method</Tag>
version{version="3"}<Tag variant="new">3</Tag>
model{model="tagger, parser"}<Tag variant="model">tagger, parser</Tag>
hidden{hidden="true"}

Elements {id="elements"}

Links {id="links"}

Markdown

markdown
[I am a link](https://spacy.io)

JSX

jsx
<Link to="https://spacy.io">I am a link</Link>

Special link styles are used depending on the link URL.

Abbreviations {id="abbr"}

JSX

jsx
<Abbr title="Explanation">Abbreviation</Abbr>

Some text with <Abbr title="Explanation here">an abbreviation</Abbr>. On small screens, I collapse and the explanation text is displayed next to the abbreviation.

Tags {id="tags"}

jsx
<Tag>method</Tag>
<Tag variant="version">4</Tag>
<Tag variant="model">tagger, parser</Tag>

Tags can be used together with headlines, or next to properties across the documentation, and combined with tooltips to provide additional information. An optional variant argument can be used for special tags. variant="new" makes the tag take a version number to mark new features. Using the component, visibility of this tag can later be toggled once the feature isn't considered new anymore. Setting variant="model" takes a description of model capabilities and can be used to mark features that require a respective model to be installed.

<p> <Tag>method</Tag> <Tag variant="new">4</Tag> <Tag variant="model">tagger, parser</Tag> </p>

Buttons {id="buttons"}

jsx
<Button to="#" variant="primary">Primary small</Button>
<Button to="#" variant="secondary">Secondary small</Button>

Link buttons come in two variants, primary and secondary and two sizes, with an optional large size modifier. Since they're mostly used as enhanced links, the buttons are implemented as styled links instead of native button elements.

<p> <Button to="#" variant="primary">Primary small</Button>

{' '}

<Button to="#" variant="secondary">Secondary small</Button>

</p> <p> <Button to="#" variant="primary">Primary small</Button>

{' '}

<Button to="#" variant="secondary">Secondary small</Button>

</p>

Components

Table {id="table"}

Markdown

markdown
| Header 1 | Header 2 |
| -------- | -------- |
| Column 1 | Column 2 |

JSX

markup
<Table>
    <Tr><Th>Header 1</Th><Th>Header 2</Th></Tr></thead>
    <Tr><Td>Column 1</Td><Td>Column 2</Td></Tr>
</Table>

Tables are used to present data and API documentation. Certain keywords can be used to mark a footer row with a distinct style, for example to visualize the return values of a documented function.

Header 1Header 2Header 3Header 4
Column 1Column 2Column 3Column 4
Column 1Column 2Column 3Column 4
Column 1Column 2Column 3Column 4
Column 1Column 2Column 3Column 4
RETURNSColumn 2Column 3Column 4

Tables also support optional "divider" rows that are typically used to denote keyword-only arguments in API documentation. To turn a row into a dividing headline, it should only include content in its first cell, and its value should be italicized:

Markdown

markdown
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Column 1 | Column 2 | Column 3 |
| _Hello_  |          |          |
| Column 1 | Column 2 | Column 3 |
Header 1Header 2Header 3
Column 1Column 2Column 3
Hello
Column 1Column 2Column 3

Type Annotations {id="type-annotations"}

Markdown

markdown
~~Model[List[Doc], Floats2d]~~

JSX

markup
<TypeAnnotation>Model[List[Doc], Floats2d]</Typeannotation>

Type annotations are special inline code blocks are used to describe Python types in the type hints format. The special component will split the type, apply syntax highlighting and link all types that specify links in meta/type-annotations.json. Types can link to internal or external documentation pages. To make it easy to represent the type annotations in Markdown, the rendering "hijacks" the ~~ tags that would typically be converted to a <del> element – but in this case, text surrounded by ~~ becomes a type annotation.

  • Dict[str, List[Union[Doc, Span]]]
  • Model[List[Doc], List[numpy.ndarray]]

Type annotations support a special visual style in tables and will render as a separate row, under the cell text. This allows the API docs to display complex types without taking up too much space in the cell. The type annotation should always be the last element in the row.

Markdown

markdown
| Header 1 | Header 2               |
| -------- | ---------------------- |
| Column 1 | Column 2 ~~List[Doc]~~ |
NameDescription
vocabThe shared vocabulary. Vocab
modelThe Thinc Model wrapping the transformer. Model[List[Doc], FullTransformerBatch]
set_extra_annotationsFunction that takes a batch of Doc objects and transformer outputs and can set additional annotations on the Doc. Callable[[List[Doc], FullTransformerBatch], None]

List {id="list"}

Markdown

markdown
1. One
2. Two

JSX

markup
<Ol>
    <Li>One</Li>
    <Li>Two</Li>
</Ol>

Lists are available as bulleted and numbered. Markdown lists are transformed automatically.

  • I am a bulleted list
  • I have nice bullets
  • Lorem ipsum dolor
  • consectetur adipiscing elit
  1. I am an ordered list
  2. I have nice numbers
  3. Lorem ipsum dolor
  4. consectetur adipiscing elit

Aside {id="aside"}

Markdown

markdown
> #### Aside title
>
> This is aside text.

JSX

jsx
<Aside title="Aside title">This is aside text.</Aside>

Asides can be used to display additional notes and content in the right-hand column. Asides can contain text, code and other elements if needed. Visually, asides are moved to the side on the X-axis, and displayed at the same level they were inserted. On small screens, they collapse and are rendered in their original position, in between the text.

To make them easier to use in Markdown, paragraphs formatted as blockquotes will turn into asides by default. Level 4 headlines (with a leading ####) will become aside titles.

Code Block {id="code-block"}

Markdown

markdown
```python
### This is a title
import spacy
```

JSX

jsx
<CodeBlock title="This is a title" lang="python">
  import spacy
</CodeBlock>

Code blocks use the Prism syntax highlighter with a custom theme. The language can be set individually on each block, and defaults to raw text with no highlighting. An optional label can be added as the first line with the prefix #### (Python-like) and /// (JavaScript-like). the indented block as plain text and preserve whitespace.

python
import spacy
nlp = spacy.load("en_core_web_sm")
doc = nlp("This is a sentence.")
for token in doc:
    print(token.text, token.pos_)

Code blocks and also specify an optional range of line numbers to highlight by adding {highlight="..."} to the headline. Acceptable ranges are spans like 5-7, but also 5-7,10 or 5-7,10,13-14.

Markdown

markdown
```python
### This is a title {highlight="1-2"}
import spacy
nlp = spacy.load("en_core_web_sm")
```
python
import spacy
from spacy.matcher import Matcher

nlp = spacy.load('en_core_web_sm')
matcher = Matcher(nlp.vocab)
pattern = [{"LOWER": "hello"}, {"IS_PUNCT": True}, {"LOWER": "world"}]
matcher.add("HelloWorld", None, pattern)
doc = nlp("Hello, world! Hello world!")
matches = matcher(doc)

Adding {executable="true"} to the title turns the code into an executable block, powered by Binder and Juniper. If JavaScript is disabled, the interactive widget defaults to a regular code block.

Markdown

markdown
```python
### {executable="true"}
import spacy
nlp = spacy.load("en_core_web_sm")
```
python
import spacy
nlp = spacy.load("en_core_web_sm")
doc = nlp("This is a sentence.")
for token in doc:
    print(token.text, token.pos_)

If a code block only contains a URL to a GitHub file, the raw file contents are embedded automatically and syntax highlighting is applied. The link to the original file is shown at the top of the widget.

Markdown

markdown
```python
https://github.com/...
```

JSX

jsx
<GitHubCode url="https://github.com/..." lang="python" />
python
https://github.com/explosion/spaCy/tree/master/spacy/language.py

Infobox {id="infobox"}

JSX

jsx
<Infobox title="Information">Regular infobox</Infobox>
<Infobox title="Important note" variant="warning">This is a warning.</Infobox>
<Infobox title="Be careful!" variant="danger">This is dangerous.</Infobox>

Infoboxes can be used to add notes, updates, warnings or additional information to a page or section. Semantically, they're implemented and interpreted as an aside element. Infoboxes can take an optional title argument, as well as an optional variant (either "warning" or "danger").

<Infobox title="This is an infobox">

If needed, an infobox can contain regular text, inline code, lists and other blocks.

</Infobox> <Infobox title="This is a warning" variant="warning">

If needed, an infobox can contain regular text, inline code, lists and other blocks.

</Infobox> <Infobox title="This is dangerous" variant="danger">

If needed, an infobox can contain regular text, inline code, lists and other blocks.

</Infobox>

Accordion {id="accordion"}

JSX

jsx
<Accordion title="This is an accordion">
  Accordion content goes here.
</Accordion>

Accordions are collapsible sections that are mostly used for lengthy tables, like the tag and label annotation schemes for different languages. They all need to be presented – but chances are the user doesn't actually care about all of them, especially not at the same time. So it's fairly reasonable to hide them begin a click. This particular implementation was inspired by the amazing Inclusive Components blog.

<Accordion title="This is an accordion">

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque enim ante, pretium a orci eget, varius dignissim augue. Nam eu dictum mauris, id tincidunt nisi. Integer commodo pellentesque tincidunt. Nam at turpis finibus tortor gravida sodales tincidunt sit amet est. Nullam euismod arcu in tortor auctor, sit amet dignissim justo congue.

</Accordion>

Markdown reference {id="markdown"}

All page content and page meta lives in the .mdx files in the /docs directory. The frontmatter block at the top of each file defines the page title and other settings like the sidebar menu.

markdown
---
title: Page title
---

## Headline starting a section {id="some_id"}

This is a regular paragraph with a [link](https://spacy.io) and **bold text**.

> #### This is an aside title
>
> This is aside text.

### Subheadline

| Header 1 | Header 2 |
| -------- | -------- |
| Column 1 | Column 2 |

```python {title="Code block title",highlight="2-3"}
import spacy
nlp = spacy.load("en_core_web_sm")
doc = nlp("Hello world")
```

<Infobox title="Important note" variant="warning">

This is content in the infobox.

</Infobox>

In addition to the native markdown elements, you can use the components <Infobox />, <Accordion />, <Abbr /> and <Tag /> via their JSX syntax.

Editorial {id="editorial"}

  • "spaCy" should always be spelled with a lowercase "s" and a capital "C", unless it specifically refers to the Python package or Python import spacy (in which case it should be formatted as code).
    • ✅ spaCy is a library for advanced NLP in Python.
    • ❌ Spacy is a library for advanced NLP in Python.
    • ✅ First, you need to install the spacy package from pip.
  • Mentions of code, like function names, classes, variable names etc. in inline text should be formatted as code.
    • ✅ "Calling the nlp object on a text returns a Doc."
  • Objects that have pages in the API docs should be linked – for example, Doc or Language.to_disk. The mentions should still be formatted as code within the link. Links pointing to the API docs will automatically receive a little icon. However, if a paragraph includes many references to the API, the links can easily get messy. In that case, we typically only link the first mention of an object and not any subsequent ones.
  • Other things we format as code are: references to trained pipeline packages like en_core_web_sm or file names like code.py or meta.json.
    • ✅ After training, the config.cfg is saved to disk.
  • Type annotations are a special type of code formatting, expressed by wrapping the text in ~~ instead of backticks. The result looks like this: List[Doc]. All references to known types will be linked automatically.
    • ✅ The model has the input type List[Doc] and it outputs a List[Array2d].
  • We try to keep links meaningful but short.