How to Add an Article

The article list on the manual home page is not hard-coded in the template. The engine reads the articles folder, loads PHP files with metadata arrays, and builds cards. A new manual is a new file. Edits are visible immediately; no separate frontend build or deploy is required.

If you are extending Microscript documentation or maintaining a local copy for your team, a clean file and a browser preview are enough. Below are the fields, naming rules, and common mistakes.

File name and URL

The file name defines the address. A file named 25-payments.php opens as /payments. The number at the beginning helps order files on disk for people. Sorting on the site is controlled by the sort field, not by the number in the name. Do not change a slug after indexing without a redirect: external links and team habits will break.

Use a Latin slug with hyphens, no spaces, and no non-Latin characters in the URL. File name format is {sortHint}-{slug}.php by your project convention.

Array fields

• title is the card and page heading.
• category is the section; a new section appears in filters automatically.
• sort is the feed position; lower numbers appear higher.
• excerpt is the short card text.
• query, seo_title, seo_description, and keywords are SEO fields when the template uses them.
• html is the article body in a <<<'HTML' heredoc.

h2 headings inside html are used for the right-side table of contents. Do not skip heading levels just for visual effect if the TOC is built simply.

Heredoc HTML

Write the body as a valid HTML fragment: p, h2, ul, ol, div class="note", and links. In a single-quoted heredoc 'HTML', PHP variables are not interpolated, which is convenient for text. Do not place the closing HTML marker on its own line inside the article text.

Internal links should be manual paths such as /birzha-frilansa, not absolute mirrors. Store images where the project already expects them and provide useful alt text.

Text style

Use a practical tone: steps, checks, and mistakes. Less filler and fewer slogans. Landing manuals can be long when they cover a product cluster; short service notes may be shorter, but keep them honestly in the start or service section.

Do not repeat the title three times in the first paragraph. Do not promise features that are not in the product. If you link to a neighboring manual, check that the file exists.

Adding step by step

1. Copy the closest article by type as a template.
2. Change the file name and slug.
3. Update metadata: title, category, sort, excerpt, and SEO fields.
4. Replace only the html body.
5. Open the manual home page; the card should appear.
6. Open the article URL and check the table of contents and links.
7. Proofread the text and check anchors.

Sorting and categories

If a card appears in the wrong place, check sort and category. Duplicate sort values may produce unstable order; leave gaps for future articles. A new category does not require template changes, but do not create synonyms for the same section.

Folder safety

In a normal configuration, the article folder is not exposed as raw PHP source through the web; output goes through the manual catalog. Still, do not put secrets, passwords, or private keys in articles. It is content, not .env.

Quality check before publishing

Read the article aloud or revisit it the next day. Check that all links open, code inside code does not break layout, lists are not empty, and note blocks do not simply repeat the previous paragraph. The SEO title should not be the H1 with five extra keywords.

Use the search phrase from query naturally, not as a comma-separated line in the first paragraph. The excerpt is for the card: one clear thought, no unfinished sentence. Choose sort values with gaps so future material can be inserted without renumbering half the section.

If the article replaces an old one, do not delete the file silently: either redirect or update content at the same slug. Stable URLs help both the team and search engines. Drafts can use a -draft suffix locally, but do not expose unfinished content in production unless the catalog supports a publish flag.

After adding an article, update related articles with links both ways. A lonely text without incoming links performs worse inside the manual.

Collaboration and git

If the manual is in git, do not edit the same file in parallel without coordination. A conflict inside heredoc is more annoying than a normal code conflict. Agree on an owner. In commits, name the slug and purpose, not "fix texts".

Do not commit temporary helper scripts into articles unless they are part of the product. Clean them after the work. The production catalog should contain only articles.

Before a large batch of new material, run a word-count or parsing check so each file returns an array without a syntax error. One broken PHP file can break the whole list if the loader does not isolate failures.

Note and list templates

Use div class="note" for one important warning, not for every paragraph. Use lists for checkable steps and field lists; do not turn the whole article into bullets. Paragraphs of different lengths read better than perfectly uniform generated sections. End with one practical takeaway, not a motivational slogan.

Before committing a large article batch, review the home page: cards should not look like clones with identical excerpts. A unique excerpt is part of the work.

Quick file self-test

Open the article in a browser, reduce the window to mobile width, and check tables and long code strings. Ensure the TOC from H2 headings is not empty and the note block makes sense. If the loader caches output, hard-refresh. Two minutes here prevent the classic "card exists, article is a mess" issue.