# Getting started

Three steps take you from a first bit to JSONL: try it in the playground,
convert it on the command line, then use the parser in your own code.

## 1. Try it in the playground

The [bitmark playground](https://getmorebrain.github.io/bitmark-playground/)
shows bitmark and its JSON side by side, with nothing to install. Paste this
bit:

```bitmark
[.article]
[@id: first-bit ]
bitmark represents content as (+bold)typed, addressable bits(-bold).
```

`[.article]` is the bit's type, `[@id: first-bit ]` its permanent ID, and
`(+bold)…(-bold)` marks the words as bold.

## 2. Convert it on the command line

Save the bit as `first.bitmark` and convert it with the parser's command-line
tool, which `npx` downloads for you:

```bash
npx @gmb/bitmark-parser convert first.bitmark --output-format jsonl
```

The result is one line of JSON per bit:

```json
{"bit":{"type":"article","format":"bitmark++","bitLevel":1,"id":["first-bit"],"body":[{"type":"paragraph","content":[{"text":"bitmark represents content as ","type":"text"},{"text":"typed, addressable bits","type":"text","marks":[{"type":"bold"}]},{"text":".","type":"text"}]}]},"parser":{"version":"7.21.2","bitmarkVersion":"3"},"bitmark":"[.article]\n[@id: first-bit ]\nbitmark represents content as (+bold)typed, addressable bits(-bold)."}
```

Each line holds the bit, the parser's version and the source it came from.
Leave out `--output-format` to get a JSON array instead; `--pretty` indents it.

## 3. Use it in your code

Install the parser and call `convert`:

```bash
npm install @gmb/bitmark-parser
```

```js
import { convert } from "@gmb/bitmark-parser";

const source = "[.article]\n[@id: first-bit ]\nbitmark represents content as (+bold)typed, addressable bits(-bold).";
const jsonl = convert(source, { inputFormat: "bitmark", outputFormat: "jsonl" });

// With warnings on, each entry's `parser` field lists what needs fixing.
const entries = JSON.parse(convert(source, { inputFormat: "bitmark", warnings: true }));
console.log(entries[0].parser.warnings ?? "no warnings");
```

The same call works in the browser and in Rust; see [The parser](https://docs.bitmark-association.org/concepts/parser.md).

## Next

- [The basics](https://docs.bitmark-association.org/concepts/basics.md): bits, tags and chains.
- [Text formatting](https://docs.bitmark-association.org/concepts/text-formatting.md): styling text with toggle tags.
- The reference lists every bit type, tag, card and resource.