npm package: @notiz/docs
Description: Components and shortcodes for notiz docs
Author: notiz
Latest version: 0.1.3

# @notiz/docs

[![npm version](https://badge.fury.io/js/@notiz%2Fdocs.svg)](https://www.npmjs.com/package/@notiz/docs)

## Installation

1. Add `@notiz/docs`, `@notiz/toolbelt` and `@notiz/shortcodes` package

```bash
npm i @notiz/docs @notiz/toolbelt@dev @notiz/shortcodes @notiz/motion
```

2. Add Tailwind CSS

```bash
# select typography and line-clamp plugin
ng add ngx-tailwind

# alternative install via
npm install -D @tailwindcss/typography @tailwindcss/line-clamp
```

3. Add Scully

```bash
ng add @scullyio/init
```

## Setup

### Angular

Add Material Icons and theme script to `index.html`

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>DocsApp</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />
    <link
      href="https://fonts.googleapis.com/icon?family=Material+Icons|Material+Icons+Round"
      rel="stylesheet"
    />
  </head>
  <body>
    <app-root></app-root>
    <script src="assets/theme.js"></script>
  </body>
</html>
```

Include assets for `@notiz/docs` via the `angular.json` including `theme.js` used above and `prism.scss` as styles.

```json
"assets": [
  {
    "glob": "**/*",
    "input": "./node_modules/@notiz/docs/assets",
    "output": "/assets/"
  }
],
"styles": [
  "src/styles.scss",
  "./node_modules/@notiz/docs/assets/prism.scss"
],
```

Add the following modules to your `app.module.ts`

```ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
import { ScullyLibModule } from '@scullyio/ng-lib';
import {
  NavbarModule,
  SideMenuModule,
  NotizDocsModule,
  ThemeModule,
  LogoModule,
  SearchPaletteModule,
} from '@notiz/docs';
import { ShortcodeModule } from '@notiz/shortcodes';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    AppRoutingModule,

    // Scully
    ScullyLibModule,

    // @notiz/docs components
    NotizDocsModule,
    SideMenuModule,
    NavbarModule,
    LogoModule,
    ThemeModule,
    SearchPaletteModule,

    // register shortcodes
    ShortcodeModule.forRoot([
      {
        shortcode: 'note',
        loadChildren: () => import('@notiz/docs').then((m) => m.NoteModule),
      },
      {
        shortcode: 'code',
        loadChildren: () => import('@notiz/docs').then((m) => m.CodeModule),
      },
      {
        shortcode: 'figure',
        loadChildren: () => import('@notiz/docs').then((m) => m.FigureModule),
      },
    ]),
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}
```

Update `app.component.ts` with following templates and docs service. Also replace the `githubRepo` name.

```ts
import { Component, OnInit } from '@angular/core';
import { DocsService } from '@notiz/docs';

@Component({
  selector: 'app-root',
  template: `
    <niz-logo>
      <a class="flex items-center space-x-3" [routerLink]="['/']">
        <img class="h-4 w-auto" src="assets/notiz.svg" alt="notiz.dev logo" />
        <span>notiz.dev</span>
      </a>
    </niz-logo>
    <niz-app>
      <niz-side-menu>
        <niz-side-menu-item
          [item]="{
            path: route.route,
            isSection: route.isSection,
            title: route.title || ''
          }"
          *ngFor="let route of docs.routes$ | async"
        >
          {{ route.title }}
        </niz-side-menu-item>
      </niz-side-menu>
      <niz-navbar>
        <a
          class="btn btn-flat space-x-3"
          [href]="'https://github.com/' + githubRepo"
          targe="_blank"
          rel="noopener"
        >
          <span>GitHub</span>
          <i class="material-icons-round text-sm">open_in_new</i>
        </a>
        <a
          class="btn btn-flat space-x-3"
          href="https://notiz.dev"
          targe="_blank"
          rel="noopener"
        >
          <img class="h-4 w-auto" src="assets/notiz.svg" alt="notiz.dev logo" />
          <span>notiz.dev</span>
        </a>
        <niz-search-button></niz-search-button>
        <niz-theme></niz-theme>
      </niz-navbar>
      <router-outlet></router-outlet>
    </niz-app>
  `,
})
export class AppComponent implements OnInit {
  githubRepo = 'notiz-dev/docs';

  constructor(public docs: DocsService) {}

  ngOnInit() {}
}
```

### Tailwind

Add a preset and a purge option for `@notiz/docs` to the `tailwind.config.js` as followed

```js
module.exports = {
  presets: [require('./node_modules/@notiz/docs/tailwind.config.js')], // 👈 preset
  content: [
    './src/**/*.{html,ts,scss}',
    './node_modules/@notiz/docs/esm2020/**/*.mjs', // 👈 include @notiz/docs styles
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

### Scully

Add a `docs` directory at root and add markdown files for your documentation. Add the following config to your `scully.projectname.config.ts`.

```ts
import { ScullyConfig } from '@scullyio/scully';
import '@scullyio/scully-plugin-puppeteer';

import './node_modules/@notiz/shortcodes/scully';
const defaultPostRenderers = ['shortcodes'];

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'project-name',
  defaultPostRenderers,
  outDir: './dist/static',
  routes: {
    '/docs/:slug': {
      type: 'contentFolder',
      slug: {
        folder: './docs',
      },
    },
  },
};
```

Create routes for your docs pages `touch src/app/docs-routing.module.ts` and add the following routes.

> **Note**: Scully and the guess parser are not able to find routes provided by an Angular library.

```ts
import { DocsModule, DocsComponent, ListComponent } from '@notiz/docs';
import { NgModule } from '@angular/core';
import { Routes, RouterModule } from '@angular/router';

const routes: Routes = [
  {
    path: '',
    component: ListComponent,
  },
  {
    path: ':slug',
    component: DocsComponent,
    data: { breadcrumb: (data: string) => data },
  },
];

@NgModule({
  imports: [DocsModule, RouterModule.forChild(routes)],
  exports: [RouterModule],
})
export class DocsRoutingModule {}
```

Add `/docs` path to `app-routing.module.ts` and use `DocsRoutingModule` created before.

```ts
import { NgModule } from '@angular/core';
import { RouterModule, Routes } from '@angular/router';

const routes: Routes = [
  {
    path: '',
    pathMatch: 'full',
    loadChildren: () => import('./home/home.module').then((m) => m.HomeModule),
  },
  {
    path: 'docs',
    loadChildren: () =>
      import('./docs-routing.module').then((m) => m.DocsRoutingModule),
    data: { breadcrumb: 'Docs' },
  },
  { path: '**', redirectTo: '' },
];

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  exports: [RouterModule],
})
export class AppRoutingModule {}
```

Each docs should at least contain `docs/getting-started.md` and `docs/installation.md`

```bash
touch docs/getting-started.md
touch docs/installation.md
```

Add frontmatter to `getting-started.md`

```md
---
title: Getting Started
published: true
weight: 0
isSection: getting-started
---
```

Add frontmatter to `installation.md`

```md
---
title: Installation
published: true
section: getting-started
weight: 10
---
```

Add scully files to `.gitignore`

```bash
# Scully
scully/**/*.js*
scully.log
src/assets/scully-routes.json
.scully/
scully.*.config.js
```