Add contributor guidance and add syntax examples

.gitignore

@@ -2,9 +2,10 @@
 node_modules
 package-lock.json
 *.vsix
-/_*
 
 # tests/integration
 .lit_test_times.txt
 **/Output/**
 
+# local drafts and examples
+docs/_*

.vscodeignore

@@ -4,8 +4,11 @@
 .gitattributes
 vsc-extension-quickstart.md
 
-# Example content (not for users)
-_strictdoc_examples/**
+# GitHub workflows, CI
+.github/**
+
+# Screenshots and extra assets (excluded from VSIX)
+assets/**
 
 # Development & test code (Node)
 parse_syntax.js
@@ -17,8 +20,13 @@ tasks.py
 requirements.txt
 tests/**
 
-# GitHub workflows, CI
-.github/**
+# Project documentation and example content (not for users)
+docs/**
 
-# Screenshots and extra assets (excluded from VSIX)
-assets/**
+# ─────────────────────────────────────────────
+# ❓ For committers: add uncertain files here
+# If you're not sure where to categorize a dev/test file,
+# list it temporarily under this section.
+# ─────────────────────────────────────────────
+# e.g.
+# temp_script.py

README.md

@@ -189,3 +189,7 @@ Now, open the `test.sdoc` file using the `Generic Text Editor`.
 You should see the SDoc syntax highlighted:
 
 ![](assets/Eclipse/Screenshot_Eclipse_12.png)
+
+---
+
+📌 See [docs/contributing.md](./docs/contributing.md) for contribution and maintenance notes.

docs/README.md

@@ -0,0 +1,11 @@
+# Documentation
+
+This folder contains internal project documentation for contributors and maintainers.
+
+## Contents
+
+- `publishing.md`: Instructions for building and publishing the VS Code extension
+- `contributing.md`: Notes for contributors
+- `examples/`: Example documents and screenshots for testing and demonstration
+
+> Avoid putting user-facing documentation in this folder. Use the main `README.md` for that.

docs/contributing.md

@@ -0,0 +1,9 @@
+# Committer Guidelines
+
+Hi! Thanks for contributing 🤝
+Just a couple of notes to keep things clean and consistent:
+
+## Dev/Test files
+
+✅ When adding development or test files, update `.vscodeignore` accordingly — exclude anything not required in the final `.vsix` package.
+Use the dedicated section at the bottom of `.vscodeignore` if unsure where a file belongs.

docs/examples/example_invalid.sdoc

@@ -0,0 +1,46 @@
+[DOCUMENT]
+TITLE: Document with deprecated REQ_PREFIX, REQUIREMENT_STYLE, REQUIREMENT_IN_TOC
+REQ_PREFIX: _DEPRECATED_
+OPTIONS:
+  REQUIREMENT_STYLE: Inline
+  REQUIREMENT_IN_TOC: True
+
+[GRAMMAR]
+ELEMENTS:
+- TAG: DEPRECATED_TYPE_REF_CHOICES
+  FIELDS:
+  - TITLE: DEPRECATED_1
+    TYPE: ParentReqReference
+  - TITLE: DEPRECATED_2
+    TYPE: FileReference
+  - TITLE: DEPRECATED_3
+    TYPE: BibReference
+
+[SOME_EXAMPLE_NODE]
+TITLE: Node with deprecated REFS tag
+REFS:
+- TYPE: File
+  VALUE: examples/example_source_files/file2.py
+
+[SECTION]
+TITLE: DEPRECATED SECTION TAG
+
+[/SECTION]
+
+[COMPOSITE_REQUIREMENT]
+STATEMENT: This tag name is possible, but will not create a composite node.
+
+[/COMPOSITE_REQUIREMENT]
+
+[ANY_NAME]
+STATEMENT: Only the composite node has a closing tag, and it has double brackets.
+
+[/ANY_NAME]
+
+[[GRAMMAR]]
+
+[[/GRAMMAR]]
+
+[[DOCUMENT_FROM_FILE]]
+
+[[/DOCUMENT_FROM_FILE]]

docs/examples/example_valid.sdoc

@@ -0,0 +1,122 @@
+[DOCUMENT]
+MID: b7bcca934cd148c3855beb4c85723bc5
+TITLE: Example document title
+UID: ABCD1234_QWERTY
+VERSION: 0.0.0.0
+CLASSIFICATION: Public
+PREFIX: FOO_SDOC-SSS-
+ROOT: True
+OPTIONS:
+  ENABLE_MID: True
+  MARKUP: RST
+  AUTO_LEVELS: On
+  VIEW_STYLE: Inline
+  NODE_IN_TOC: True
+METADATA:
+  FOO: BAR
+
+[GRAMMAR]
+ELEMENTS:
+- TAG: NODE_NAME_ONE
+  PROPERTIES:
+    IS_COMPOSITE: True
+    PREFIX: None
+    VIEW_STYLE: Narrative
+  FIELDS:
+  - TITLE: MID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: LEVEL
+    TYPE: String
+    REQUIRED: True
+  - TITLE: PREFIX
+    TYPE: String
+    REQUIRED: True
+  - TITLE: STATUS
+    TYPE: String
+    REQUIRED: False
+  - TITLE: TAGS
+    TYPE: Tag
+    REQUIRED: False
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: True
+  - TITLE: STATEMENT
+    TYPE: String
+    REQUIRED: False
+  - TITLE: RATIONALE
+    TYPE: String
+    REQUIRED: False
+  - TITLE: COMMENT
+    TYPE: String
+    REQUIRED: False
+  RELATIONS:
+  - TYPE: Parent
+    ROLE: Implements
+  - TYPE: Child
+    ROLE: Refines
+  - TYPE: File
+- TAG: NODE_NAME_TWO
+  FIELDS:
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: True
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: True
+  - TITLE: VERIFICATION
+    TYPE: MultipleChoice(Review, Analysis, Inspection, Test)
+    REQUIRED: True
+  - TITLE: FIELD_ONE
+    TYPE: SingleChoice(A|B|C)
+    REQUIRED: False
+  - TITLE: FIELD_TWO
+    TYPE: MultipleChoice(A|B|C)
+    REQUIRED: False
+
+[[NODE_NAME_ONE]]
+MID: 668d18a7489043b38dd435933319e8
+UID: ABC-123
+LEVEL: None
+STATUS: Draft
+TAGS: one, two
+TITLE: Example composite node title
+STATEMENT: System A shall do B.
+RATIONALE: Rationale.
+COMMENT: Test comment.
+RELATIONS:
+- TYPE: Parent
+  VALUE: SDOC-SSS-88
+  ROLE: Refines
+- TYPE: Parent
+  VALUE: SDOC-SSS-58
+  FUNCTION: Foo.hello_world_2
+
+[NODE_NAME_TWO]
+UID: QWE-6789
+TITLE: Example non-composite node title
+VERIFICATION: Review, Test
+FIELD_ONE: A
+FIELD_TWO: B, C
+
+[[/NODE_NAME_ONE]]
+
+[SOME_EXAMPLE_NODE]
+STATEMENT: >>>
+MathJax in requirement's STATEMENT:
+
+.. raw:: latex html
+
+    $$
+    \mathbf{\underline{k}}_{\text{a}} =
+    \mathbf{\underline{i}}_{\text{a}} \times
+    \mathbf{\underline{j}}_{\text{a}}
+    $$
+<<<
+
+[DOCUMENT_FROM_FILE]
+FILE: ddd/ddd/ddd\f456inc-_lude.ssec
+INCLUDE_TITLE: True

docs/publishing.md

@@ -0,0 +1,85 @@
+# Publishing the StrictDoc VSCode Extension
+
+This document explains how to package and publish the extension to the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/).
+
+## 1. Checklist before publishing
+
+* ✅ Version in `package.json` has been bumped.
+* ✅ Only necessary files are included in the `.vsix` package.
+* ✅ `.vscodeignore` is up-to-date and excludes:
+
+  * tests/\*\*
+  * parse\_syntax.js
+  * .github/\*\*
+  * assets/\*\*
+  * node\_modules/\*\* (if not needed at runtime)
+  * any other internal scripts or data
+
+## 2. Bump the version
+
+### 2.1. manually (recommended)
+
+Update `version` in `package.json` (manually):
+
+```json
+"version": "0.2.1"
+```
+
+> ⚠️ This must be **higher** than the currently published version.
+
+### 2.2. automatically via npm version
+
+You can also use:
+
+```bash
+npm version patch|minor|major
+```
+
+it will:
+  * Update the version number in package.json and package-lock.json;
+  * Automatically create a Git commit with a message like v0.2.2;
+  * Create a Git tag with the same version name (v0.2.2).
+
+If you want to avoid creating the commit and tag, use the --no-git-tag-version flag:
+
+```bash
+npm version patch --no-git-tag-version
+```
+
+## 3. Build the extension
+
+Run:
+
+```bash
+vsce package
+```
+
+This generates a `.vsix` file (e.g., `strictdoc-0.2.1.vsix`).
+
+## 4. Publish to Marketplace
+
+If not logged in:
+
+```bash
+vsce login StrictDoc
+```
+
+To publish:
+
+```bash
+vsce publish
+```
+
+## 5. Verify
+
+Check that the version and content appear here (may take a minute or two):
+
+* [https://marketplace.visualstudio.com/items?itemName=StrictDoc.strictdoc](https://marketplace.visualstudio.com/items?itemName=StrictDoc.strictdoc)
+
+---
+
+## Notes
+
+* Images used in `README.md` will be loaded from GitHub if paths are relative.
+* You don't need to ship them inside `.vsix`.
+* Use the `docs/` folder for internal notes, not visible on Marketplace.