Bundle a README#

Sysand Index presents a bundled README.md as the project README on the project page. Use this guide to give visitors a description of what your project is, what it contains, and what they should know before using it. A README is optional, but strongly recommended.

To follow this guide you need an existing Sysand project. See Creating your first project if you do not have one yet.

Bundle the file#

Create a README.md file next to the .project.json and .meta.json files in the project root:
```
project-directory/
  .project.json
  .meta.json
  README.md
```

Run sysand build and confirm that the README is picked up:

$ sysand build
    Building kpar `/path/to/my-project/output/my_project-0.0.1.kpar`
   Including readme from `/path/to/my-project/README.md`

After you publish the built .kpar file, the README appears on the project page.

README.md files are expected to contain Markdown. See Markdown support for the supported Markdown syntax.

What to include#

The README is the first thing visitors see on the project page, and it is the piece of documentation users are most likely to read before deciding whether to depend on your project. Many readers skim, so lead with a one-line description that communicates the project’s purpose on its own.

Most project READMEs benefit from covering:

What the project is: one or two sentences naming the modeling domain and the kind of elements it exposes (parts, requirements, libraries, templates), and what problem they solve.
How to start using it: the sysand add command for adding the project as a usage, plus a minimal .sysml snippet that imports something useful from it. A short import snippet is more useful than a paragraph describing what the project exposes.
What’s inside: a short tour of the top-level packages or files so readers can navigate the model.
Compatibility: the SysML v2 or KerML release identifier the project targets, and any required dependencies beyond the OMG standard library.
Where to get help: a link to the source repository, issue tracker, or contact address for questions and bug reports.

Tutorials, design rationale, and full API references usually live better in the source repository than in the bundled README. Link out to them instead.