Writing guide

The three steps

1. 1Write – title, optional summary and the article itself, in the editor described on this page.
2. 2Preview – the article exactly as readers will see it, with "Back to edit" if something needs fixing.
3. 3Publish – who can read it, category and tags, learning path, reader interactions and where it is published, on one page.

Nothing is lost between steps: the article is a draft in My Stories until you press "Publish now", and you can stop at any point and come back later.

The page

Title

Up to 100 characters, required. Say what the reader will learn; under 60 characters shows in full in search results. Enter moves on to the summary.

Summary

Optional, up to 300 characters: one or two sentences shown under the title, on article cards, in search results and in the emails your followers get. Leave it empty and the opening of your text is used instead.

Cover image

The first image in the article is the cover: it is what cards, the publish page and social previews show. Put your best image first if you want a specific cover.

Article

No length limit. Each paragraph is its own line: Enter starts a new one, a "+" appears next to every empty line (the block menu, below), and selecting text shows the formatting toolbar.

Auto-save

Five seconds after you stop typing (title, summary or text) the draft is saved on its own – the green dot and "Auto-save enabled" at the top left of the editor tell you it is on. A new article gets its draft, and its own address, on the first auto-save. If a save fails the next change simply tries again.

Save draft

Saves right away and keeps you in the editor, where you were. "Save & close" in the header saves the draft too and then takes you to My articles, so closing the editor never loses work. Without a title or any text the page says so instead of leaving.

Preview

Saves, then opens step 2: the article laid out as readers will get it, including code highlighting, formulas and the "On this page" list.

Publish

The green button saves and opens the publish page directly (step 3), for when you have already previewed.

? and fullscreen

"?" opens this guide in a popup. Fullscreen hides the site header and the side panel so only the article is on screen; press it again to leave.

Side panel

The strip on the right (arrow to open) shows title and summary counters, word and character counts, reading time and a Quality Score with one tip at a time. The score rewards a title of 30+ characters, a summary, 600+ words, several paragraphs, headings, at least a couple of images / code blocks / lists / embeds, a link and sentences under about 22 words. It is guidance while you write, not a gate.

The + menu: images, code, tables and more

Put the cursor on an empty line and a + appears at its left; click it for the block menu. The block replaces the empty line, and a new paragraph is created under it so you can keep writing. Every block can be removed: hover it and use its Delete button, or undo with Ctrl+Z.

Image

Uploads a picture from your computer (the file is checked and stored by MLHub). Hover the image for its size buttons – Small (25%), Medium (50%), Large (75%), X Large (the text width, the default) and Full Screen – and Delete. The box under the image is the caption (optional); it is shown centred under the picture. Use it for: screenshots of a result, charts and plots you made, architecture drawings, a photo of your setup. Example: a loss curve, X Large, captioned "Loss after 20 epochs". The first image of the article also becomes its cover.

Unsplash

A search box for free Unsplash photos: type a topic, press Search, click one of the six results. It is inserted as a normal image block (same sizes and caption) with the "Photo by … on Unsplash" credit already in the caption. Delete removes the search box if you change your mind. Use it for: a cover or a mood picture when you have no image of your own – a city at night for an article on traffic forecasting. Keep the credit in the caption.

Video

Asks for a link and inserts a player: YouTube (also youtu.be, Shorts and links with a start time), Vimeo, Loom, or a direct https link to a .mp4 / .webm / .ogg video file. Videos are not uploaded to MLHub: put the file on a video site first. Add an optional caption under the player; hover for Delete. Pasting a YouTube or Vimeo link into an empty line does the same without the menu. Use it for: a demo of what you built, a conference talk you discuss, a screen recording of a tricky setup step. A YouTube link with ?t=90 starts the video at 1:30.

Embedding

Asks for a link and embeds it live: CodePen, CodeSandbox, JSFiddle, StackBlitz, GitHub Gist, Spotify, SoundCloud, Figma, Google Docs / Sheets / Slides / Forms and Hugging Face Spaces (plus the video sites above). Any other link – including another MLHub article or a post on a social network – becomes a link card with a title you can type. Use it for: things readers should try or explore rather than read: a Hugging Face Space where they can test your model, a CodePen they can edit, a full script in a Gist, a Google Sheet with your results, a Figma design, a podcast episode. Link cards point to further reading.

Table

A small dialog asks for rows (1–20, including the header), columns (1–10), width (100%, 75%, 50% or auto), alignment (centre, left, right) and whether the first row is a header. Click a cell to type; Tab / Shift+Tab and Enter move between cells. The size is fixed once inserted, so count your rows first; hover the table for the delete button. Use it for: numbers and comparisons readers will scan: model results (accuracy, F1, training time), library A vs library B, hyperparameters and their values, a glossary. Example: a 4 × 3 comparison of models with a header row. A table of a few words per cell reads best; long explanations belong in paragraphs.

Code Block

Pick the language from the list (Python, JavaScript, TypeScript, Java, C, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, R, Perl, Lua, HTML, CSS, SCSS, XML, JSON, YAML, Markdown, SQL, GraphQL, TOML, Dockerfile, Nginx, Apache, Regex, Bash, Shell, PowerShell, Dart, Elixir, Haskell, Clojure or plain text) and type or paste the code. Readers get syntax colours, line numbers and a Copy button. See "Code blocks" below. Use it for: anything a reader may copy and run: a function, a training loop, a terminal command, a config file, a SQL query, program output (choose Plain Text). For a single name inside a sentence use inline code from the toolbar instead.

Math Expression

Opens the formula editor (LaTeX with a live preview, buttons for common symbols and a formula library) and inserts the formula as a centred block. See "Math" below. Use it for: equations the text depends on: a loss function, the softmax, Bayes' rule, a gradient update. Put each important formula in its own block and explain its symbols in the paragraph after it.

Flowchart

Opens the flowchart builder: start from a template, list your steps as cards or type them as arrows, and the chart is drawn and arranged for you – no dragging boxes. See "Flowcharts" below. Use it for: any process with an order or a choice in it: an ML pipeline, how a RAG system answers, an agent's loop, a sign-in flow, a debugging checklist, a decision ("Is the data clean? yes / no").

Table of Contents

A "Table of Contents:" box listing every line you set to Large (ToC) in the text size menu, as links that jump to it. It updates itself as you add or rename those lines. Use it for: long tutorials and guides with several sections: insert it after your first paragraph so readers can jump straight to the part they need. Short articles do not need one (the article page already shows "On this page" in the margin).

Divider

A horizontal rule between two sections. Hover it for Delete. Use it for: a change of topic or pace that does not need a heading: between the story and the code, before a "Further reading" list, before an update added later.

New Part

A chapter break: two rules with an editable title, numbered automatically ("Part 1", "Part 2" …). Click the title to rename it. Use it for: long walkthroughs in stages, where each part is a milestone: "Part 1: Getting the data", "Part 2: Training the model", "Part 3: Deploying it". For a whole series of separate articles use a learning path on the publish page instead.

Text formatting

Select some text and the toolbar appears above it. Buttons that change the whole line (text size, quote, attention block, drop cap, background, row underline) work on the paragraph the selection is in; the others format just the selected words. Click a button again to remove what it added.

Undo, Redo

The editor keeps its own history of every change. Ctrl+Z and Ctrl+Y work anywhere on the page.

Bold, Semi-bold, Italic

Bold (Ctrl+B) for key terms, the lighter semi-bold for labels, italic (Ctrl+I) for titles of works and emphasis.

Underline, Strikethrough

Ctrl+U underlines; strikethrough is handy for "was 0.8, now 0.6" corrections.

Link

Ctrl+K or the chain button opens a small dialog: paste the URL, optionally change the link text (it is pre-filled with your selection) and press Add Link. Links open in a new tab for readers.

Inline code

The { } button sets the selection in a monospace font for a file name, a flag or a short expression inside a sentence, like --epochs 20. For whole snippets use a Code Block.

Superscript, Subscript

x², H₂O, footnote marks. Select the character(s) first.

Text size (T)

Hover the T for a menu of line sizes: Large (ToC), Medium-Large, Medium, Small and Normal to reset. Large (ToC) turns the line into a real section heading (an h2) and Medium-Large into a sub-heading (h3): both are what the Table of Contents block and the article page's "On this page" list use. Medium and Small only change the size of a normal line. The size applies to the whole line, and the article page uses the same typography, so what you see is what readers get.

Drop cap

Makes the first letter of the paragraph large, magazine style. Use it once, on the opening paragraph.

Background colour

Gives the paragraph a soft coloured background (twelve pastel swatches, or the checkered one to remove it). Good for a short note the reader must not miss.

Quote

Turns the paragraph into a block quote with the vertical bar; press it again to turn it back. For citing a paper, a docstring or someone's words.

Attention block

A highlighted callout paragraph for warnings and tips ("This deletes the index – back it up first"). Press it again to make it a plain paragraph.

Row underline

A line under the whole paragraph, whatever its width – a lightweight way to set off a heading line.

Clear formatting

The scissors remove everything at once: the line's size, quote, attention, drop cap, underline and background, plus the bold / italic / code / links inside the selection. Click inside a resized line without selecting anything and the toolbar appears just for this button – used that way it also turns the whole line into plain text.

Lists

There is no list button: lists are typed. At the start of an empty line type 1. and a space for a numbered list, or - / * and a space for bullets. The line becomes the first item the moment you type the space. The green "?" at the bottom right of the editor repeats these rules.

Enter

Next item at the same level. On an empty last item it leaves the list and gives you a normal paragraph; in a sub-list it goes back up to the main level instead.

Tab

On an empty item (press Enter first), makes it a sub-item of the item above. There is one level of sub-items; sub-items of a numbered list show as bullets and sub-items of a bulleted list are numbered. Tab does nothing on an item that already has text, and nothing inside a sub-item.

Shift + Tab

In a sub-item, moves it back to the main level with its text.

Ctrl + Enter

A new line inside the same item, for an item that needs two sentences or a short explanation under a bold first line. Shift + Enter does the same in a main item; in a sub-item it takes you back to the main level.

Backspace

At the start of an item, joins it to the item above. On the first (or only) item it turns the list back into a paragraph – the quickest way to undo a conversion you did not want.

Arrow keys

Up at the start of an item and Down at its end move between items as you would expect.

Code blocks

• Insert: + menu → Code Block → choose the language. The language is fixed for that block (delete it and insert another to change it); the badge in its header shows which one it is.
• Typing: the block is plain text while you edit – Enter makes a new line and Tab inserts four spaces. Syntax colours, line numbers and the Copy button appear on the preview and the published article.
• Pasting: paste inside the block and you get the raw text, exactly as copied: every line break and indentation is kept and nothing is reformatted. Paste code outside a block and it is treated as ordinary text.
• Full: opens the block in a large overlay to read or edit a long file; Esc or Exit closes it. Readers have the same button.
• Delete: the bin in the block header, after a confirmation.
• Example: a Python block with the training loop, then a Bash block with the one command to run it.

Math

+ menu → Math Expression opens the formula editor. Write LaTeX in the box and the preview renders it as you type (after a short pause); the buttons above insert common pieces – fraction, square root, sum, integral, product, limit, Greek letters, hats and vectors – and the Formula Library below fills the box with a complete formula in one click (Famous formulas, AI & ML such as sigmoid, softmax, attention and KL divergence, algebra, calculus, statistics …). Insert Formula puts it in the article as a centred block; hover the block for Edit (back to the editor with the formula loaded) or Delete. On the article page formulas are rendered with MathJax.

E = mc²

E = mc^2 – ^ raises, _ lowers: x_i^2.

Fraction

\frac{a}{b}, for example the sigmoid \sigma(z) = \frac{1}{1 + e^{-z}}.

Sum, product

\sum_{i=1}^{n} x_i, \prod_{k=1}^{K} p_k.

Roots, integrals

\sqrt{x}, \int_{0}^{1} f(x)\,dx.

Words in a formula

\text{ReLU}(x) = \max(0, x).

Formulas inside a sentence are not supported: put a short formula in inline code, or give it its own block.

Flowcharts

+ menu → Flowchart opens the builder. You describe the steps and the arrows; MLHub draws the shapes and arranges them for you – you never place or connect boxes by hand. The builder has three tabs that edit the same chart, so you can switch between them at any time.

Templates

The builder opens here. Pick a ready-made chart – Blank, Simple process, Yes / No decision, ML training pipeline, RAG question answering, AI agent loop, Sign-in flow or Debugging checklist – then change its words in Steps or Write. The quickest start: choose the template closest to your idea.

Steps

One card per shape. Type the step's text, choose its shape and use “Goes to…” to draw an arrow to another step (or to “+ a new step”); an arrow can carry a short label. A Question card offers “Add Yes / No answers”. The arrows on a card move it up or down, ✕ deletes it, “+ Add a step” adds one at the end, and Enter in a card adds the next step.

Several lines

A step can hold several lines (up to ten): Shift+Enter or “+ line” under the text starts a new line in the same step, and lines that start with “- ” are drawn as a bulleted list inside the shape. Pasting several lines into a card works too. Example: a step “Outputs” with the lines “- accuracy” and “- confusion matrix”.

Write

Type the whole chart as text, one arrow (or a chain of arrows) per line; the preview follows as you type, and a problem (such as a step with no text) is shown with its line number. A step ending with “?” becomes a question and Start / End words become rounded ends on their own. Mermaid flowchart text can be pasted as it is (flowchart LR as the first line sets left-to-right).

Layout and colour

Above the preview choose ↓ Top to bottom or → Left to right, and one of six colour themes (indigo, emerald, sky, amber, rose, slate). Shapes are placed and connected for you; arrows that go back to an earlier step (loops, retries) are drawn dashed. Click a shape in the preview to jump to its card.

Caption

Optional, under the chart: say what it shows (“How the model is trained”). Then Insert flowchart; Cancel or Esc closes the builder without changing the article.

Change it later

Hover the chart in your article for Edit (the builder opens with everything as you left it) or Delete; double-clicking the chart opens it too. A chart holds up to 60 steps.

Readers see the same chart on the preview and the article page, in light or dark mode. Screen readers and the article narrator get the steps as text, so write each step so that it makes sense read aloud.

Pasting from elsewhere

• From a web page, Google Docs, Word or Notion: the structure is kept – headings, paragraphs, bullet and numbered lists, quotes, links, bold, italic, underline, strikethrough, inline code, images, tables with their header cells – and the source's fonts, sizes, colours, spacing and hidden wrappers are dropped, so the text takes MLHub's typography. Each pasted heading, list or quote becomes its own editor block.
• Plain text with several lines: one paragraph per line, so a chapter copied from a text file lands as paragraphs, not as one wall of text.
• Markdown: recognised and converted – #, ##, ### headings, **bold**, *italic*, `code`, [text](url) links, - bullet lists, > quotes and fenced ``` code. Numbered 1. lines arrive as items; images and tables written in Markdown do not convert.
• A bare link on an empty line: a YouTube, Vimeo or other supported link is embedded right away (see Video / Embedding); any other link is pasted as text.
• Into a code block: always the raw text, never converted.

Import a story

Already published the article on your own blog or another platform? Writer Tools → Import a story takes the article's link, fetches the page, converts it into a draft (title, text, images) and opens it in this editor for you to tidy up and publish. You must confirm that you wrote the article and have the right to publish it on MLHub – importing someone else's work is not allowed – and imports are limited to ten an hour.

Headings and "On this page"

The article page shows an "On this page" list in the margin, with the reader's position highlighted, whenever it finds at least two sections. It is built from real headings (lines set to Large (ToC) or Medium-Large, or ## / ### headings from pasted Markdown or a pasted page) and, when there are none, from the two ways writers usually mark a section: a short line that is entirely bold, or a short Title Case line with no full stop followed by a paragraph. So give every section a title on its own line and set it to Large (ToC) (a real heading) – sub-sections to Medium-Large. Two sections are enough for the list to appear.

Publishing

• Preview first: it is the article page itself. Check images, code and formulas, then "Continue".
• The publish page holds everything on one form: who can read it (free – everyone, including visitors – or premium, for paying members), the category and tags (both required, up to ten tags, popular ones suggested as you type), an optional learning path and part number if the article belongs to a series, and which reader interactions are on (comments, claps, likes, saving, sharing, the popularity graph). Then where it lives: under your own name or under one of your public organizations; members of a private organization publish inside it, for the whole organization or chosen teams. "Save as draft" keeps every choice without publishing.
• Publish now makes the article live at its address and notifies your followers (and the organization's, if any) by email and in-app once. The article gets a writing-quality check on the way: articles below the quality threshold, or containing blocked words, are held for an administrator to review before anyone can read them – you are told on the article page, and it goes live as soon as it is approved.
• Editing after publishing: open the article and choose "Edit article" in its "…" menu. Your changes go into a draft (My Stories) while the published version stays online unchanged; publishing the draft again replaces it and bumps the version. The category, tags, tier and other settings can be changed on the same publish page.

Keyboard shortcuts

• BoldCtrl + B
• ItalicCtrl + I
• UnderlineCtrl + U
• Link (with text selected)Ctrl + K
• UndoCtrl + Z
• RedoCtrl + Y
• New paragraphEnter
• Title → summary → articleEnter / Tab
• List: sub-item / main levelTab / Shift + Tab
• List: line break in an itemCtrl + Enter
• Table: next / previous cellTab / Shift + Tab
• Code block: indent / leave fullscreenTab / Esc
• Flowchart card: next step / new lineEnter / Shift + Enter

On a Mac, use ⌘ instead of Ctrl for bold, italic, underline, link, undo and redo.

A good article

• Open with the problem you solve, not with background.
• One idea per section, with a heading line that says what it is.
• Show real code, numbers or examples, and credit your sources.
• Finish with what the reader can do next.
• Use Preview before you publish: it shows exactly what readers get.