# Writing articles

> Write an article about a product you built, with its files, live preview and install command in the text: the blocks and their syntax, pictures, the review of your first two, and what's refused.

Developers write articles about the products they built: what each one does, how it works, how it was made and what
was hard, with the product's own files, its live preview and its install command inside the text. Every article has a
page of its own at `https://upfork.dev/articles/<name>`, is listed at [/articles](https://upfork.dev/articles) (in the site's menu, and on the
home page), and shows on its product's page and on its developer's.

## Who writes

A developer with a public page writes about **one of their own products**: each article names one. For UpFork's own
products, the developer credited with building them writes about them. Everyone reads articles, guests too.

Write one from the developer panel, **Articles**: choose the product, and the editor opens on a draft only you see.
The editor has the Markdown on one side and the article as it will read on the other, with the title, the summary,
the product, the tags and the cover. Save with **Save** or Ctrl+S (⌘+S on a Mac).

## The text

Articles are Markdown, GitHub's flavour: `##` and `###` headings (they make the article's contents), **bold**,
_italics_, `code`, links, lists, tables, quotes, and code blocks fenced with three backticks, highlighted in light and
dark. HTML isn't shown.

- **Title:** up to 100 characters.
- **Summary:** up to 200, in a sentence or two. Search engines show it under the title.
- **Tags:** up to 5 of the site's own tags (the ones products have); the product's come first.
- **Length:** up to 100 kB of text. The reading time counts the words, code left out.

## Blocks

The product's own pieces go on a line of their own, between paragraphs (inside a list or a quote, a block is just its
text). Every one is checked when you save: the editor lists what's wrong, and an article can't go out until it's put
right.

### A file

```text
::file{path="components/hero/lens.ts" lines="10-30"}
```

Lines 10 to 30 of the product's file, highlighted and numbered as in the file, with **Open in the code browser**, which
opens the product's page on those lines. `lines="12"` shows one line; leaving `lines` out shows the whole file. A block
shows 300 lines at most.

The lines are kept as they read when you saved the article, so the article reads the same however the product moves on.
Once the file has changed, readers see "Written for revision 12; the file has changed since", with the lines as they are
now a click away.

**A paid product** (one with a price, or in a paid plan) can't be given away by its article: a block shows 60 lines at
most, and an article 200 lines in all.

### The live preview

```text
::preview{demo="default"}
```

The product's live preview, as its page shows it: its poster first, then the preview itself, with its demos, themes
and widths. `demo` picks the demo it opens on; leave it out for the first.

### The install command

```text
::install
```

The product's install command, as **Get it** shows it, in npm, pnpm, yarn and bun. A free product in no plan installs
by its address, with no account; the others with the reader's access token.

### A callout

```text
:::callout{kind="tip"}
Keep the spring soft: a stiffness of 120 reads as weight.
:::
```

A note, a tip or a warning (`kind="note"`, `"tip"` or `"warning"`), in its colour. It can hold any Markdown, and closes
with a line of `:::`. A one-line callout can also be written `::callout[Keep the spring soft.]{kind="tip"}`.

## Pictures

**Picture** in the editor's toolbar uploads a PNG, JPEG, WebP or GIF of up to 5 MB and puts it in the text as a
Markdown picture, `![Describe the picture](its address)`: write what it shows between the brackets, which is its caption
and what screen readers read. **Cover** sets the picture at the top of the article and on its cards; without one, the product's
own picture is used. Only pictures uploaded to the article show: a picture from another site would load from anywhere,
and isn't shown.

## Publishing and the review

Your **first two articles** are read by UpFork before they go out. Press **Send for review**: it waits in UpFork's queue,
and you're told when it's published, or sent back with a note of what to change (you read it in the editor). While it
waits you can take it back to change it.

From your third approved article on, **Publish** publishes at once.

A published article can be changed: edit it, and **Publish changes** (or **Send changes for review**, before your first
two are approved). Readers see the published version until then, so they never read a half-written one, and every
version that was published is kept. A published article keeps its address and its product.

A draft that was never published can be deleted, with its pictures. A published one stays: change it, or ask Support.

## What's refused

Nothing secret goes public. Every save is read for **keys and tokens** (UpFork's `upf_…`, GitHub's, AWS's, OpenAI's,
Anthropic's, Stripe's, Slack's, Google's, a Telegram bot's, JWTs), **private keys**, **e-mail addresses** and **IP
addresses**, and refused with what was found and on which line. For examples, use the documentation's own:
`info@example.com`, `203.0.113.10`, a private address such as `192.168.1.10`, or `YOUR_KEY`.

UpFork can hide an article that breaks the rules (copied from elsewhere, an advert for something else, harmful code),
with a reason its author reads in the editor and by e-mail. If you think it was a mistake, open a ticket at
[Support](https://upfork.dev/support/new?topic=articles).

## Found by search engines

Each article has its own description for search engines (a TechArticle by its author, about its product), its own
picture for link previews, and its place in the sitemap. An article of fewer than 300 words isn't listed by search
engines. Each article is also served as Markdown for AI assistants, at its address plus `.md`.

## On your page and your résumé

Your [developer page](https://upfork.dev/docs/profile) counts your articles beside your products and views, and lists your newest four.
Your PDF résumé prints up to four of them, in the order you choose (your newest three until you choose), each title
linked to its page; its verification page lists them too, and counts how many you've published.

## Views

An article's views count once per reader a day; its author's own and UpFork's admins' don't count, nor search engines'
crawlers. Your articles' views are on your **Articles** page.

## Questions about articles

Open a ticket on the topic **Articles and lessons** at [Support](https://upfork.dev/support/new?topic=articles), with the article's
address if it's about one: support sees it beside your message.

Page: https://upfork.dev/docs/articles