Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/manoelcampos/asciidoc-github-template

Template para elaboração de material didático multimídia com AsciiDoc, git e GitHub para publicação no GitHub Pages. Use o repositório e altere como quiser para publicar seu próprio material. E tudo é automaticamente publicado no GitHub Pages 📖
https://github.com/manoelcampos/asciidoc-github-template

asciidoc github github-actions github-pages publishing template

Last synced: about 2 months ago
JSON representation

Template para elaboração de material didático multimídia com AsciiDoc, git e GitHub para publicação no GitHub Pages. Use o repositório e altere como quiser para publicar seu próprio material. E tudo é automaticamente publicado no GitHub Pages 📖

Awesome Lists containing this project

README

        

:revealjsdir: https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.8.0
:revealjs_slideNumber: true
:source-highlighter: highlightjs
:icons: font
:allow-uri-read:
:imagesdir: /images
:stylesheet: adoc-golo.css
:numbered:
ifndef::env-github[:toc: left]
:toc-title: Sumário
:toclevels: 5

ifdef::env-github[:outfilesuffix: .adoc]

ifdef::env-github,env-browser[]
// Exibe ícones para os blocos como NOTE e IMPORTANT no GitHub
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]

:chapter-label:
:description: Elaboração de material didático multimídia com AsciiDoc, git e GitHub
:listing-caption: Listagem
:figure-caption: Figura

= Template para Elaboração de Material Didático Multimídia com AsciiDoc, git e GitHub

IMPORTANT: Você pode baixar uma versão sempre atualizada em PDF deste material https://github.com/manoelcampos/asciidoc-github-template/blob/gh-pages/ebook.pdf[aqui].

ifdef::env-github[image:https://github.com/manoelcampos/asciidoc-github/workflows/asciidoctor-ghpages/badge.svg[GitHub Pages]]

Este repositório serve como um template para a criação de material didático multimídia utilizando
AsciiDoc e hospedando no GitHub Pages.
Ele apresenta instruções de como configurar seu ambiente de desenvolvimento
para poder escrever conteúdo em AsciiDoc e publicar no GitHub Pages.
Adicionalmente, há um resumo dos comandos AsciiDoc para quem estiver iniciando
na produção de conteúdo neste formato.

Assim, utilize este arquivo README.adoc como exemplo pois ele já está configurado.
Para criar seu próprio conteúdo, basta apagar o texto neste arquivo e incluir
o seu. Quando for criar novos arquivos, basta copiar o README.adoc anterior
e iniciar a partir daí.

== Instalação das Ferramentas no seu Ambiente de Desenvolvimento

Execute o script link:ferramentas.sh[ferramentas.sh] em um terminal com sistema Ubuntu ou qualquer derivado de Debian:

[source, bash]
----
sh ferramentas.sh
----

Se sua distribuição for antiga ou não for 64 bits, pode ser que a instalação do Visual Studio code não funcione. Se ocorrer erro, baixe o Visual Studio Code manualmente em http://code.visualstudio.com

Crie uma conta no GitHub em https://github.com/signup. O nome de usuário se torna o link para sua conta pública, como http://github.com/manoelcampos. Por isso, escolha o nome apropriadamente.

Para qualquer alteração em um projeto que você desejar enviar para o GitHub a partir da sua máquina, você precisará informar nome de usuário e senha. Isso se tornará um processo bastante chato e toma tempo. Para evitar isso, na nossa máquina pessoal, podemos configurar a autenticação por meio de um par de chaves pública/privada.

ifdef::env-github[]
Para isto, siga o tutorial disponível https://youtu.be/j7lX9ff9rC8[neste vídeo].
endif::[]

ifndef::env-github[]
Para isto, siga o tutorial do vídeo abaixo.

.Autenticação baseada em chave no GitHub a partir do Linux
video::j7lX9ff9rC8[youtube, width=640, height=480]
endif::[]

ifdef::backend-pdf[]
include::comandos.adoc[]
endif::[]

ifndef::backend-pdf[]
== Comandos AsciiDoc

// A sintaxe abaixo tambem gera um link como o comando link::[],
// mas neste caso apontando diretamente para o arquivo comandos.adoc
// Usando tal sintaxe, se estivermos na interface do GitHub ou em um
// arquivo html gerado a partir de um adoc,
// a extensão .adoc será substituída por html.

<>

// O comando xref deveria fazer o mesmo, mas não está funcionando
// quando o adoc é convertido para html fora da interface do GitHub (como no GitHub Pages por exemplo)
// xref:comandos.adoc[Um resumo dos comandos AsciiDoc está disponível aqui.]

endif::[]

== GitHub Pages

O repositório usa a https://github.com/manoelcampos/asciidoctor-ghpages-action[AsciiDoctor GitHub Pages Action] para converter cada arquivo `adoc` para `html`, enviando tais arquivos para o branch `gh-pages`. Este processo ocorre automaticamente sempre que um push é executado ou pull request enviada. Com isto, o material estará disponível em um site no GitHub Pages em `http://seu-nome-de-usuario.github.io/nome-do-seu-repositorio`.

IMPORTANT: É necessário incluir o branch `gh-pages` como fonte de publicação para seu site GitHub Pages nas configurações do seu repositório. https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site[Instruções aqui].

== Licença

Este repositório não possui uma licença definida e você pode utilizar o conteúdo dele livremente
para criar seu próprio repositório. Assim, não é preciso dar qualquer tipo de crédito por ter utilizado
este projeto (a menos que realmente queira).

Você pode utilizar tal repositório como bem desejar, sem qualquer tipo de limitação.
No entanto, o repositório é fornecido como está e nenhuma responsabilidade será
atribuída ao autor do mesmo.

Ao produzir seu conteúdo multimídia a partir deste respositório,
é importante adicionar um arquivo LICENSE e assim definir
explicitamente uma licença para o conteúdo que você produzir.

== Referências

- https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Official Writer’s Guide]
- https://asciidoctor.org/docs/[Toda a Documentação oficial do AsciiDoc]
- https://github.com/darshandsoni/asciidoctor-skins[Temas em CSS]