Pré-requisitos

  • Instalar o Pandoc - \\dypevm03\downloads\desktop team\pandoc-1.19.2.1-windows.msi;
  • Instalar o Miktex - \\dypevm03\downloads\desktop team\basic-miktex-2.9.6236-x64.exe;
  • Instalar o node.js - choco install nodejs -y
  • Instalar o mermaid de linha de comando - npm install -g mermaid.cli
  • Estar com a pasta c:\infra\ atualizada pelo SVN;
  • Estar com a pasta c:\dype\source\desktop.release\Gestor\ atualizada pelo SVN;

Estrutura

  • Dentro da pasta c:\dype\source\desktop.release\Gestor\ uma pasta Docs\Manuais.
  • O script c:\infra\_desktop\suporte\BuildManuais.ps1 irá criar/atualizar nas soluções do Freshdesk uma categoria com o nome Gestor - Manuais.
  • Depois de criar a categoria, o script irá varrer as pastas dentro da pasta Docs\Manuais criando pastas com o mesmo nome do Freshdesk dentro da categoria Gestor - Manuais.
  • E da mesma forma, para cada pasta, irá criar um artigo para cada arquivo com a extensão .markdown dentro das pastas.
  • A visibilidade das pastas é definida pelo nome. Pastas começando com Documentação Interna serão visíveis apenas para agentes enquanto que todas as outras serão públicas para qualquer pessoa na internet visualizar.
  • Não é possível utilizar subpastas pois o freshdesk só permite um nível.

Veja na imagem a seguir a estrutura de pastas e um arquivo .markdown de exemplo.

  1. O caminho da estrutura da pasta VERSÃO\Docs\Manuais\;
  2. A pasta de arquivos que irá virar uma pasta de artigos no Freshdesk;
  3. Um arquivo .markdown que irá virar um artigo no Freshdesk (podemos ter diversos arquivos em cada pasta);
  4. Um arquivo de imagem que é utilizado dentro do .markdown e vira uma imagem embutida no artigo do Freshdesk;

--

Estrutura de pastas e arquivos

E na imagem a seguir o resultado no freshdesk. Colocamos os marcadores em azul, para não confundir com os marcadores em amarelo da imagem de exemplo.

  1. A categoria criada com o número da versão correto;
  2. A pasta criada com o mesmo nome da pasta que está dentro do Docs\Manuais;
  3. O título do artigo sendo o nome do arquivo .markdown;
  4. A imagem que está dentro da mesma pasta e referenciada dentro do arquivo .markdown;

Resultado no Freshdesk

Como Atualizar os Artigos no Freshdesk

Basta executar o script c:\infra\desktop\suporte\BuildManuais.ps1.
É importante fazer commit no SVN de todas as alterações nos arquivos .markdown_ ou imagens.

Problemas e Soluções

  • Problema: Os acentos não aparecem no artigo no freshdesk;

  • Solução: O arquivo .markdown tem que ser editado no formato UTF8;

  • Problema: As barras \ não aparecem no artigo no freshdesk;

  • Solução: Dentro do .markdown as barras são indicadores de comandos para o pandoc. Para aparecer uma barra no texto, devemos usar duas barras no .markdown desta forma \\;

  • Problema: Minha alteração num artigo desapareceu do freshdesk;

  • Solução: Não altere artigos desta estrutura diretamente no freshdesk, eles são sobrescritos a cada execução do BuildManuais.ps1;

  • Problema: Apaguei um .markdown do SVN mas o artigo não sumiu do freshdesk;

  • A exclusão de artigos não é automática. Remova manualmente do freshdesk ou remova toda a categoria para ser recriada. O problema disso é que os links publicados se perdem pois tudo ganha um novo ID;

TODO

  • Criar um job manual ou com um período grande como uma semana no Jenkins para fazer update e executar o script de atualização;
    ** Isso fará com que o commit dos .markdown e imagens seja obrigatório e também remove a necessidade da instalação do Pandoc e Miktex localmente no PC;
  • Escrever uma explicação sobre o merge entre as pastas docs em diferentes versões;
  • Criar uma forma de criar links dinâmicos entre soluções sem saber o link real da solução;
    ** Creio que terá que ser uma solução em duas passadas dentro do próprio BuildManuais.ps1, uma para criar tudo e outra para trocar um texto LINK-xxx para a url correta usando o Get-FreshdeskSolution;