@notiz/docs

v0.1.3

Published

2 years ago

Components and shortcodes for notiz docs

Downloads

0High
0Medium
0Low

garygrossgarten

marcjulian

@notiz/docs

Installation

Add @notiz/docs, @notiz/toolbelt and @notiz/shortcodes package

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

Add Tailwind CSS

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

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

Add Scully

ng add @scullyio/init

Setup

Angular

Add Material Icons and theme script to index.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.

"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

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.

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

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.

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.

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.

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

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

Add frontmatter to getting-started.md

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

Add frontmatter to installation.md

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

Add scully files to .gitignore

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@notiz/docs

Installation

Setup

Angular

Tailwind

Scully