ZhijuCen
148 lines
5.4 KiB
Markdown
148 lines
5.4 KiB
Markdown
# 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: ``.
|
|
- 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}`.
|