npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

md2poui

v4.0.0

Published

Conversor de arquivos markdown para páginas Angular com suporte ao PO-UI

Downloads

21

Readme

md2poui

Conversor de arquivos markdown para componentes Angular utilizando recursos visuais das bibliotecas PO UI.

Instalação

npm install md2poui -g

ou

npm install md2poui --save-dev

Modo de uso

const md2poui = require('md2poui');
md2poui('C:/pathFromMdFiles', 'C:/pathToAngularFiles');

ou

md2poui C:/pathFromMdFiles C:/pathToAngularFiles

Release Notes

4.0.0

  • Atualizado para para rodar com a versão 15 do po-ui e node 18.

3.0.0

  • Removido suporte ao Portinari UI e adicionado suporte somente ao PO-UI.
  • Removida a criação de âncoras, devido a limitação técnica do PO-UI.

2.0.2

  • Inclusão do campo de filtro no menu da página inicial.

2.0.1

  • Corrigida geração da página inicial ao usar nome de módulo com mais de uma palavra.
  • Corrigida geração de componentes que possuem números no início do nome.

2.0.0 Nova Versão!

  • Removido suporte ao THF.
  • Adicionada nova configuração: options.home.

    Mais informações disponíveis no item options.

1.2.5

  • Corrigido parâmetro parentRoutePath na versão CLI - por @laraujo0901.

1.2.4

  • Melhoria na conversão das imagens para que as mesmas não gerem barra de rolagem horizontal para a página.
  • Corrigidas configurações padrões.
  • Corrigida geração de componentes onde a pasta contém números que representam sua ordem de criação.

1.2.3

  • Adicionado suporte ao PortinariUI!
  • Adicionadas novas configurações: options.portinariUi e options.parentRoutePath.

    Mais informações disponíveis no item options.

  • A partir desta versão, se definida a configuração options.flatDirs=false o menu será gerado de forma hierárquica obedecendo a estrutura dos arquivos markdown.
  • Adicionado suporte a diretórios na lista de exclusões.
  • Alterado nome do método que retorna os itens para getMenuItems.
  • O módulo de rotas agora possui fallback para caminhos inválidos.

1.2.1, 1.2.2

  • Adicionadas novas configurações: options.recursive e options.highlightClassName.

    Mais informações disponíveis no item options.

  • Adicionado suporte a arquivos no parâmetro de origem.

1.2.0

  • Adicionado suporte à execução do md2poui "globalmente" via linha de comando.

1.1.1 e 1.1.2

  • Corregidas dependências utilizadas pelo projeto.

1.1.0

  • Adicionado suporte a ícones do padrão do GitHub. Exemplo: :warning: será :warning: - por @marcospds.
  • Adicionadas novas configurações: options.createHelpers e options.copyExternalFiles.

    Mais informações disponíveis no item options.

1.0.2

  • Corrigida verificação das configurações padrões quando não era informado exclusions.
  • Adicionado suporte a links internos na geração dos componentes.
  • Adicionado suporte à âncoras para títulos de até três níveis.

1.0.1

  • Primeira versão!

Parâmetros

function md2poui(srcPath: string, destDir: string, options?: Options): void {}

srcPath

Caminho de origem dos arquivos markdown que serão convertidos. São considerados todos os arquivos com extensão .md encontrados na pasta raiz e nas subpastas do caminho informado.

Exemplo: C:/zoologico.

destDir

Diretório de destino dos arquivos Angular que serão criados a partir da conversão dos arquivos markdown.

Exemplo: C:/portal/src/app/zoologico.

Arquivos existentes no diretório de destino não são excluídos.

options

Opções de configurações e definições customizadas de conversão dos arquivos:

{
  exclusions: string[] = [],
  highlightClassName: string = 'highlight',
  flatDirs: boolean = false,
  recursive: boolean = true,
  createHelpers: boolean = true,
  home: boolean = true,
  moduleName: string = 'docs',
  parentRoutePath: string = '{{moduleName}}',
  copyExternalFiles: boolean = true,
  resourceFolderName: string = 'assets',
  resourcePathName: string = 'app/{{moduleName}}/{{resourceFolderName}}'
}

options.exclusions

Lista com os arquivos markdown ou diretórios que serão desconsiderados da conversão. O caminho informado nesta lista pode ser relativo ou completo ao diretório informado no parâmetro srcPath.

Valor padrão: [] Exemplo: ['C:/zoologico/onca/README.md', 'chimpanze/README.md'].

options.highlightClassName

Nome da classe CSS que será utilizada nos elementos de códigos de exemplo.

Independente desta configuração, a classe contendo o nome da linguagem sempre é inserida.

Valor padrão: highlight.

options.flatDirs

Se verdadeiro, irá criar as pastas dos componentes na pasta raíz da pasta de destino informada no parâmetro destDir, caso contrário irá obedecer a mesma estrutura encontrada na pasta de origem informada no parâmetro srcPath.

Valor padrão: true

Exemplo:

srcPath

C:\
└── zoologico\
    └── animais\
    │   └── leao\
    │   |   ├── README.md
    │   └── zebra\
    │   |   ├── README.md
    └── atracoes\
    │   ├── README.md
    ├── README.md

destDir com options.flatDirs=true

C:\portal\src\app\
└── zoologico/
    └── leao/
    │   ├── leao.component.ts
    └── zebra/
    │   ├── zebra.component.ts
    └── atracoes/
    │   ├── atracoes.component.ts
    ├── zoologico.component.ts
    ├── zoologico.module.ts
    ├── zoologico.service.ts
    ├── zoologico-routing.module.ts

destDir com options.flatDirs=false

C:\portal\src\app\
└── zoologico/
    └── animais/
    │   └── leao/
    │   |   ├── leao.component.ts
    │   └── zebra/
    │   |   ├── zebra.component.ts
    └── atracoes/
    │   ├── atracoes.component.ts
    ├── zoologico.component.ts
    ├── zoologico.module.ts
    ├── zoologico.service.ts
    ├── zoologico-routing.module.ts

options.recursive

Se verdadeiro, irá ler recursivamente todas as pastas abaixo da pasta de origem informada no parâmetro srcPath.

Valor padrão: true.

options.createHelpers

Se verdadeiro, irá criar os arquivos auxiliares de módulo, rotas e serviço.

Valor padrão: true.

options.home

Se verdadeiro, irá criar uma página inicial já com menu para os componentes criados.

Valor padrão: true.

options.moduleName

Nome do módulo Angular que será criado para agrupar os componentes gerados a partir da conversão dos arquivos markdown.

Valor padrão: docs.

O nome do módulo deve ser informado em kebab-case.

options.parentRoutePath

Caminho da rota pai que será utilizado para as rotas dos componentes.

Valor padrão: {{options.moduleName}}.

Exemplo:

options.parentRoutePath='zoo/animais'

{
  label: "Leão",
  link: "zoo/animais/leao"
}

options.copyExternalFiles

Se verdadeiro, irá copiar os arquivos externos referenciados nos arquivos markdown para a pasta de recursos.

Valor padrão: true.

options.resourceFolderName

Nome da pasta de recursos que será criada para armazenar os arquivos externos referenciados nos arquivos markdown.

Os arquivos encontrados na conversão são copiados para dentro desta pasta com um nome único gerado automaticamente para não haver conflitos e as referências são alteradas para apontar para o arquivo copiado.

Valor padrão: assets.

Esta pasta deve ser incluída como asset da aplicação Angular.

Geralmente estes arquivos são imagens referenciadas pela marcação markdown ou HTML, como nos exemplos abaixo: > ![Minha Imagem](imagens/minhaImagem.png) ou > <img alt="Minha Imagem" src="imagens/minhaImagem.png" />

options.resourcePathName

Caminho que será utilizado para referenciar os arquivos externos copiados durante a conversão dos arquivos markdown.

Padrão: src/app/{{options.moduleName}}/{{options.resourceFolderName}}.

Este caminho deve ser acessível pela aplicação Angular.

Facilitadores

Além da conversão e criação dos componentes Angular são criados mais três arquivos auxiliares: módulo, rotas e serviço.

O arquivo de módulo agrega todos os componentes criados e o roteamento destes componentes - com o uso do arquivo de roteamento.

Já o arquivo de serviço possui facilitadores para retornar a lista das rotas dos componentes no formato esperado pelo menu do PO-UI.

Module

import { NgModule } from '@angular/core';
import { PoModule } from '@po-ui/ng-components';

import { WikiRoutingModule } from './wiki-routing.module';
import { WikiService } from './wiki.service';

import { SampleComponent } from './sample/sample.component';

@NgModule({
  declarations: [SampleComponent],
  imports: [PoModule, WikiRoutingModule],
  providers: [WikiService]
})
export class WikiModule {}

Routing

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

import { SampleComponent } from './sample/sample.component';

const routes: Routes = [
  {
    path: 'sample',
    component: SampleComponent
  }
];

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

Service

import { Injectable } from '@angular/core';
import { PoMenuItem } from '@po-ui/ng-components';

@Injectable({
  providedIn: 'root'
})
export class WikiService {
  constructor() {}

  public getWikiMenuItems(): PoMenuItem[] {
    return [
      {
        label: 'Sample Component',
        link: 'wiki/sample'
      }
    ];
  }
}

Visualização dos arquivos externos

Os arquivos externos referenciados nos arquivos markdown são copiados para a pasta de recursos (conforme parâmetros options.copyExternalFiles e options.resourceFolderName) com outro nome gerado dinâmicamente.

Para que seja possível a visualização dos arquivos desta pasta pela aplicação Angular é necessário adicionar a pasta de recursos como asset alterando o arquivo angular.json da aplicação:

{
  "assets": [
    "src/favicon.ico",
    "src/assets",
    "src/app/zoologico/resources"
  ]
}

Feito com md2poui

Toda a área de documentação do portal TOTVS Java Framework foi desenvolvida utilizando o md2poui.