feat(doc-builder): [molecule] DocPage [2h]

[mesqueeb]

prerequisite

• feat(markdown): Markdown; MarkdownSection; CodeBlock components [3h] #13

goal

need a DocPage component that can host multiple examples and an API Card at the bottom

eg.

---

---

it's a matter of creating a component out of this code:
https://github.com/cycraft/blitzar/blob/production/packages/docs/src/pages/DocsPage.vue
(you don't need to use the composition api)

problem with current implementation

One problem with the current implementation is that there's no way to have regular markdown chapters in between examples.

We see it's a problem with eg. "Events" In which I want to show 1 main example, then 2 other examples with H2 titles, instead of rendering the "Events 2" and "Events 3" H1 titles as well.

required implementation details

have the user pass two props:

• "pathToDocPageFolder"
• "chapterOrder"

The chapterOrder should be the file names (without extension) inside the "doc page files folder". It can be a combination of .vue and .md files. Whenever it's a .vue file, it's rendered with <ExampleSection />. Whenever it's an .md file, it's rendered with <MarkdownSection />. (see #14)

Now we have a mix of examples and just markdown sections, but then we need to know if the titles of each markdown / example are H1s or H2s.

The solution to that is to not render H1s based on the file names, like I'm doing now in the Blitzar docs. But force the dev to add # Some Title manually to each example/markdown section.

steps

• this component is to be called DocPage.vue and is to be create inside a new directory at packages/doc-builder
• copy paste a package.json from any other package (api-card, example-card, ...)
• update package name to be @planetar/doc-builder
• clear out all the package dependencies
• lerna add @planetar/example-card --scope @planetar/doc-page
• lerna add @planetar/markdown --scope @planetar/doc-page
• add the package to the dev project so you can develop: lerna add @planetar/doc-builder --scope dev
• npm run dev
• make a dev page for in the dev project for the new DocPage component (check other examples when you open the dev server)

other requirements

• The component needs to somehow create and emit a TOC after rendering (to be able to pass to feat(doc-builder): [atom] TableOfContents [2h] #11)
• This TOC needs to be based on all the h1 & h2 titles
• write in a way it's easy later to expand to deeper levels

probably the easiest way for this TOC to implement is using javascript to "look" at the DOM rendered in the mounted hook. This method is good enough for now.