volto-code-block

O que é

Complemento para Volto com três blocos para quem escreve sobre tecnologia:

  • Bloco de Código: código-fonte com destaque de sintaxe, botão de copiar e legenda.
  • Diagrama Mermaid: diagramas desenhados a partir de uma definição em texto.
  • Bloco Gist: incorpora um Gist público do GitHub, inteiro ou apenas um de seus arquivos.

Os três blocos também funcionam dentro dos blocos de grade e acordeão.

Exemplos

Todos os exemplos abaixo são blocos de verdade, com legenda, usados nesta própria página.

Bloco de Código

from plone import api

noticias = api.content.find(
    portal_type="News Item",
    review_state="published",
    sort_on="effective",
    sort_order="reverse",
)

for brain in noticias[:5]:
    print(brain.Title, brain.getURL())

As cinco notícias mais recentes

Busca no catálogo com plone.api, em Python.

Tema escuro e tamanho grande.

[project]
name = "meu.complemento"
version = "1.0.0"
dependencies = ["plone.api"]

Um pyproject.toml mínimo

TOML é a linguagem nova da versão 4.0.0.

Tema claro e tamanho médio.

Diagrama Mermaid

flowchart LR
  A["Agente de IA"] -->|"quais blocos existem?"| B["Servidor MCP"]
  B -->|"consulta"| C["@blocks-schema"]
  C -->|"documentação e schema"| B
  B -->|"grava os blocos"| D["Página no Plone"]

A definição do diagrama

O texto que vai no bloco, mostrado aqui em um Bloco de Código.

Como um agente aprende a usar os blocos

O mesmo texto, desenhado pelo Diagrama Mermaid.

Este é o caminho que levou estes exemplos até a página.

Bloco Gist

Plone com Docker, em um Gist de 2022

A página guarda só a referência; o navegador busca o conteúdo no GitHub.

O Gist usa uma imagem antiga do Plone 6: está aqui apenas para mostrar o bloco.

Como usar

Em um projeto Plone 6 com Volto, adicione @plonegovbr/volto-code-block às chaves addons e dependencies do arquivo package.json. O complemento é desenvolvido e testado com o Volto 19.6.

"addons": [
    "@plonegovbr/volto-code-block"
],
"dependencies": {
    "@plonegovbr/volto-code-block": "*"
}

Trecho do package.json

Acrescente as duas entradas às listas que o projeto já tem.

Depois, instale as dependências e inicie o Volto. Na pasta frontend do projeto, execute:

make install
make start

Instalação e início

Na raiz do projeto, os comandos são make frontend-install e make frontend-start.

Em seguida, edite uma página e escolha Bloco de Código, Diagrama Mermaid ou Bloco Gist no grupo de texto do seletor de blocos. A legenda fica na aba Legenda da barra lateral: ela só aparece quando o título está preenchido.

Novidades da versão 4.0.0

  • Documentação dos três blocos para o endpoint @blocks-schema do Volto 19.6.
  • Legenda no Diagrama Mermaid; tamanho e alinhamento nos blocos de código e Gist.
  • Nova linguagem: TOML.
  • Botão de copiar de volta ao lugar e sempre visível; a opção de quebrar linhas longas voltou a funcionar.
  • Código com linguagem desconhecida ou sem linguagem definida agora é exibido, em vez de causar erro.

Documentação para agentes e MCP

A partir do Volto 19.6, o endpoint @blocks-schema descreve os blocos de um site para quem está autenticado. Cada bloco deste complemento publica ali o seu docs.block.md, com campos, exemplos e schema. Assim, um agente conectado por MCP aprende a escrever estes blocos sem precisar de instruções feitas à mão. Os exemplos desta página foram gravados dessa forma.

{
  "@type": "codeBlock",
  "code": "print(\"Plone Brasil!\")",
  "language": "python",
  "style": "dark",
  "caption_title": "Olá, Plone",
  "caption_description": "Um bloco com legenda."
}

Os dados de um Bloco de Código

É isto que um agente envia para criar um bloco com legenda.