mql5-skills/docs-dev/naming.md

Naming Convention — Folder & File Structure

This document specifies how sitemap URLs map to the file tree under skills/mql5/references/book/ and skills/mql5/references/docs/.

Core Rules

1. One subfolder level: Under book/ or docs/, at most one level of subfolder (the "chapter folder") is used. All pages within that chapter are .md files directly inside the chapter folder.

2. pics/ exception: Each chapter folder may contain a pics/ subfolder for images extracted from that chapter's pages.

3. Sequential numbering: Both chapter folders and files carry numeric prefixes that reflect their order in the source sitemap.

Chapter Folders

A "chapter" corresponds to the first URL path segment after the sitemap root.

Source URL pattern	Chapter folder
/en/book/intro ...	00-intro/
/en/book/basis ...	01-basis/
/en/docs/basis ...	00-basis/
/en/docs/standardlibrary …	34-standardlibrary/

• Prefix: 2-digit zero-padded number (00, 01, 02, …)
• Suffix: the URL path segment (e.g. intro, basis, standardlibrary)
• Order: by first occurrence in the sitemap

Chapters are numbered globally within each sitemap (book and docs are independent numbering spaces).

Files Within a Chapter

Each URL that belongs to a chapter becomes one .md file inside the chapter folder. The filename encodes:

{4-digit global number}-{derived-name}.md

• 4-digit prefix: sequential number matching the URL's position in the sitemap (0001, 0002, …). This is global across the entire sitemap, not reset per chapter.
• Derived name: the URL path after the depth-1 segment, with / replaced by -. If the URL is the depth-1 segment itself (the chapter index page), the name is the segment name.

Derived-name rules

| URL path (after /en/{book|docs}/) | Chapter folder | File name | |-------------------------------------|----------------|---------------------| | intro | 00-intro/ | 0001-intro.md | | intro/edit_compile_run | 00-intro/ | 0002-edit-compile-run.md | | basis | 01-basis/ | 0015-basis.md | | basis/syntax | 01-basis/ | 0016-basis-syntax.md | | basis/types/integer/integertypes | 01-basis/ | 0019-basis-types-integer-integertypes.md | | standardlibrary/mathematics/... | 34-standardlibrary/ | 1143-standardlibrary-mathematics-....md |

Root-level URLs

The very first URL in each sitemap (e.g. https://www.mql5.com/en/book or https://www.mql5.com/en/docs) has no depth-1 segment. It is placed directly under the references root as:

0000-book.md      (for book sitemap)
0000-docs.md      (for docs sitemap)

Complete Example — Book (first 20)

skills/mql5/references/book/
├── 0000-book.md                              # /en/book
├── 00-intro/
│   ├── 0001-intro.md                         # /en/book/intro
│   ├── 0002-edit-compile-run.md              # /en/book/intro/edit_compile_run
│   ├── 0003-mql-wizard.md                    # /en/book/intro/mql_wizard
│   ├── ...
│   └── pics/
├── 01-basis/
│   ├── 0015-basis.md                         # /en/book/basis
│   ├── 0016-basis-identifiers.md             # /en/book/basis/identifiers
│   ├── 0017-basis-builtin-types.md           # /en/book/basis/builtin_types
│   ├── 0018-basis-builtin-types-integer-numbers.md
│   ├── ...
│   └── pics/
├── 02-oop/
│   ├── ...
│   └── pics/
...

Complete Example — Docs (first 20)

skills/mql5/references/docs/
├── 0000-docs.md                              # /en/docs
├── 00-basis/
│   ├── 0001-basis.md                         # /en/docs/basis
│   ├── 0002-basis-syntax.md                  # /en/docs/basis/syntax
│   ├── 0003-basis-syntax-commentaries.md     # /en/docs/basis/syntax/commentaries
│   ├── 0004-basis-syntax-identifiers.md
│   ├── 0005-basis-syntax-reserved.md
│   ├── 0006-basis-types.md
│   ├── 0007-basis-types-integer.md
│   ├── 0008-basis-types-integer-integertypes.md
│   ├── ...
│   └── pics/
├── 01-constants/
│   ├── ...
│   └── pics/
...

Image Handling

• Images are saved to pics/ within the chapter folder where they appear.
• Filenames: {original-filename} or {derived-name}.png if no useful name.
• The Markdown reference uses a relative path: ![alt](pics/image.png).
• Per extraction spec: the <img> alt text is taken from the next sibling <p> element's innerHTML, not duplicated.

Name Sanitization

When converting URL segments to file/folder names:

Character	Replacement
_	-
/	- (within filename)
Uppercase	lowercase
Non-alphanumeric (except -)	removed

Example: builtin_types → builtin-types, MQL_Wizard → mql-wizard.

Validation

A post-extraction script should verify:

1. Every sitemap URL has exactly one output file.
2. File numbers are sequential with no gaps.
3. No file exceeds the 4-digit range (max 9999 URLs per sitemap).
4. Chapter folder names match the expected pattern: {NN}-{segment}.