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
eoptions.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 arquivosmarkdown
. - 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
eoptions.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
eoptions.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çãoAngular
.
Geralmente estes arquivos são imagens referenciadas pela marcação
markdown
ouHTML
, 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
.