Ultimas correcciones de documentacion antes de la version 0.1.0
This commit is contained in:
174
README.md
174
README.md
@@ -1,130 +1,108 @@
|
|||||||
# Mail-comment
|
# Mail-Comment
|
||||||
|
|
||||||
Prototipo de idea de comentarios para Blogs basado en E-Mail
|
|
||||||
|
|
||||||
¿Por que no? Vamos aprovechando los recursos existentes que estoy asumiendo que tienes ya que quieres y puedes montarte un blog.
|
Prueba de concepto para añadir comentarios en sitios estáticos utilizando **correo electrónico**.
|
||||||
|
Prototype to add comments to static sites using **email**.
|
||||||
|
|
||||||
> Adelanto que esto solo es una prueba de concepto. en lo personal, las alternativas que analizamos son mas completas y funcionales y solo busco añadir una opción a la lista de alternativas existentes.
|
---
|
||||||
|
|
||||||
Mail-Comment es una prueba de concepto de comentarios en paginas estáticas basado en correo electrónico. De la misma forma en la que buscaba otros usos para IMAP, se me ocurrió esta idea, notandole algunas ventajas interesantes.
|
## 📋 Características / Features
|
||||||
|
|
||||||
- Soberanía digital. Tus datos son tuyos. Los datos de tus seguidores son solo los que comparten entre ustedes en una comunicación normal de Correo Electrónico.
|
- **Sin registro / No registration**: cualquier usuario con correo electrónico puede comentar / any user with email can comment.
|
||||||
- Panel de moderación improvisado. Antes de hacer públicos los comentarios que recibes, puedes aprovechar los filtros de SPAM existentes y controlar que quieres publicar o no.
|
- **Moderación / Moderation**: aprovecha filtros de spam del proveedor de correo / use existing spam filters.
|
||||||
- Control adicional de SPAM. Agrega filtros y palabras clave para controlar el SPAM
|
- **Filtros / Filters**: palabras clave y dominios específicos / keywords and domain filters.
|
||||||
- Multiples salidas. Elije la que mas te convenga según la plataforma que tengas.
|
- **Exportación / Export options**: HTML, Markdown, RSS/XML.
|
||||||
- Filtro de dominio. Añade reglas que permitan participar específicamente en el post elegido.
|
- **Integración / Integration**:
|
||||||
- Widgets y botones. Puedes configurarlos en tu sitio para facilitar el proceso.
|
- Hugo: añade comentarios al final de los posts / append comments to Hugo posts.
|
||||||
- Compatibilidad con Hugo. Añade los comentarios directo en tus post de Hugo.
|
- WordPress: webhook para instancias *headless* / webhook for headless WordPress.
|
||||||
- Minimalismo total. Sin javascript añadido. Sin Iframes y sin necesitar otros servidores, propios o ajenos.
|
|
||||||
|
|
||||||
## Características
|
---
|
||||||
|
|
||||||
- No necesita registro. Cualquiera puede escribir un comentario, siempre y cuando tenga un correo electrónico
|
## ⚙️ Instalación / Installation
|
||||||
- Identidad. (esto hay que revisar) Identificate con tu nombre de usuario de correo electrónico
|
|
||||||
- Compatibilidad con diferentes estrategias.
|
|
||||||
- Comentarios por archivos RSS. Puedes añadir un widget que lea archivos XML a modo de comentarios.
|
|
||||||
- Comentarios estáticos HTML. Exporta los comentarios como fragmentos HTML que puedes integrar en tu página.
|
|
||||||
- Comentarios estáticos MarkDown. Exporta los comentarios como fragmentos MarkDown que puedes integrar en tu pagina.
|
|
||||||
- Integración con Hugo. En tu instancia local, añade los comentarios al final de tus archivos MarkDown de hugo, según la url comentada.
|
|
||||||
- Integración con Wordpress. Añade un webhook en tu servidor de Wordpress para recibir los comentarios sobre una URL para una instancia Headless.
|
|
||||||
|
|
||||||
Dado que es un prototipo, estaré analizando mas cosas y mejoras que hacer.
|
```bash
|
||||||
|
|
||||||
# Instalación y ejecución
|
|
||||||
|
|
||||||
En linux necesitas crear un venv, te adjunto también los comandos para crearlo y ejecutarlo, pero recuerda que tienes que editar el archivo .env
|
|
||||||
|
|
||||||
```
|
|
||||||
git clone https://git.interlan.ec/Drk0027/mail-comment.git
|
git clone https://git.interlan.ec/Drk0027/mail-comment.git
|
||||||
cd mail-comment
|
cd mail-comment
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
cp .env.example .env
|
cp .env.example .env
|
||||||
python -m venv
|
python -m venv venv
|
||||||
source venv/bin/activate
|
source venv/bin/activate
|
||||||
python email-processor.py
|
python email-processor.py
|
||||||
```
|
```
|
||||||
|
|
||||||
Te he dejado un archivo .env.example para que lo copies a .env y configures según tus necesidades. Recuerda que necesitas un servidor IMAP, que puede ser el de tu correo electrónico.
|
## 📄 Configuración .env / .env Configuration
|
||||||
|
|
||||||
> Advertencia
|
```python
|
||||||
>
|
env
|
||||||
> Recuerda que publicar tu dirección de correo puede ser algo sensible. Puede exponerte a SPAM y puede arriesgarte a que pillen alguna vulnerabilidad y terminen causándote daño. Te recomiendo que si quieres utilizar este enfoque, crees una cuenta nueva para esta tarea.
|
DOMAIN_TO_SEARCH=midominio.com
|
||||||
>
|
IGNORE_KEYWORDS=publicidad,notificacion,spam
|
||||||
> Nota
|
|
||||||
>
|
|
||||||
> En el estado actual, el script revisa todos los correos de la carpeta INBOX, pero solo borra los que cumplan los requisitos de los que hablaremos mas adelante. Esto es por seguridad. Así, si quieres hacer pruebas, no terminaras con toda tu bandeja aniquilada.
|
|
||||||
>
|
|
||||||
> También, el script analiza uno por uno los correos dentro de la bandeja que has especificado. Si esta muy llena o si tu servidor es muy lento, esta tarea puede tardar mucho.
|
|
||||||
|
|
||||||
Si bien, es posible utilizar el correo de gmail, es algo de lo que tengo dudas y no he tenido la oportunidad de probar todavia. Parece que se puede utilizar una clave de aplicacion, si alguien lo intenta, puede decirme para actualizar este post. Aun así, en teoría puedes usar los mismos servidores que usarías en delta chat.
|
|
||||||
|
|
||||||
https://providers.delta.chat/
|
|
||||||
|
|
||||||
|
|
||||||
# Flujo de trabajo
|
|
||||||
|
|
||||||
Publica normalmente como siempre haces. Añade un texto o un botón para indicar a los usuarios como realizar los comentarios, mediante correo electrónico. Para que funcione esta herramienta, el asunto debe contener la url de la pagina que se desee comentar. Esto sirve de validación para separar el spam de los comentarios legítimos.
|
|
||||||
|
|
||||||
Por supuesto, si no quieres agregar el botón o crees que el enlace mailto no funciona, puedes pedir que te escriban directo desde sus bandejas de entrada, indicando en el asunto la url del post que deseas que comenten.
|
|
||||||
|
|
||||||
[Comentar esta entrada por correo electrónico](mailto:drk0027@interlan.ec?subject=https://interlan.ec/blog/2026/01/16/comentarios-en-sitios-estaticos/)
|
|
||||||
|
|
||||||
En el archivo .env deberás configurar el DOMAIN_TO_SEARCH con tu dominio para poder localizar el destino de los comentarios. Esto también te evitará algo de SPAM puesto que los procesos automatizados no saben que estarás utilizando este sistema de comentarios (a menos que se haga popular y los crawlers terminen aprendiendo como funciona y empiecen a joder simulando ser usuarios legítimos)
|
|
||||||
|
|
||||||
En el archivo .env tambien puedes configurar palabras clave que puedes usar a modo de filtro mediante IGNORE_KEYWORDS=publicidad,notificacion,spamintroduce todas las palabras que quieras usar. Pero esto es mas útil si eliges ejecutar este script de forma regular, con poca o ninguna supervisión.
|
|
||||||
|
|
||||||
Al ser un correo normal, puedes revisar la bandeja de entrada para leer lo que ha llegado y decidir si lo borras o lo dejas antes de ejecutar el programa. Usa tu bandeja de entrada a modo de panel de moderación y de esta manera, puedes incluso aprovechar los filtros de tu proveedor de correos, como gmail, que usualmente es muy efectivo.
|
|
||||||
Elije una o todas las opciones de exportación o integración.
|
|
||||||
|
|
||||||
```
|
|
||||||
SAVE_HTML=True
|
SAVE_HTML=True
|
||||||
SAVE_MARKDOWN=True
|
SAVE_MARKDOWN=True
|
||||||
SAVE_XML=True
|
SAVE_XML=True
|
||||||
SEND_WEBHOOK=True
|
SEND_WEBHOOK=True
|
||||||
```
|
|
||||||
|
|
||||||
Si estas usando una instancia Headless de wordpress, puedes utilizar un snippet o editar un plugin o tema para integrar y crear un nuevo webhook para recibir los comentarios.
|
|
||||||
|
|
||||||
https://git.interlan.ec/Drk0027/mail-comment/src/branch/main/functions.php
|
|
||||||
|
|
||||||
```
|
|
||||||
WP_WEBHOOK_URL=https://tusitio.com/wp-json/tudominio/v1/recibir-comentario
|
WP_WEBHOOK_URL=https://tusitio.com/wp-json/tudominio/v1/recibir-comentario
|
||||||
WEBHOOK_SECRET_TOKEN=mi_clave_secreta_123
|
WEBHOOK_SECRET_TOKEN=mi_clave_secreta_123
|
||||||
|
|
||||||
|
HUGO_DIR=/home/user/quickstart/
|
||||||
|
APPEND_HUGO=True
|
||||||
```
|
```
|
||||||
|
|
||||||
Si estas usando Hugo, agrega el directorio donde estas editando tu sitio.
|
## ▶️ Ejecución / Run
|
||||||
|
```bash
|
||||||
```
|
|
||||||
HUGO_DIR = /home/user/quickstart/
|
|
||||||
APPEND_HUGO = True
|
|
||||||
```
|
|
||||||
|
|
||||||
Esta función prepara todos los comentarios recibidos y los agrega al final de tus entradas en Hugo que correspondan a la URL equivalente.
|
|
||||||
|
|
||||||
Solo lo he probado con un despliegue básico de Hugo. Por eso se llama QuickStart XD
|
|
||||||
|
|
||||||
Ejecuta el script.
|
|
||||||
|
|
||||||
Recuerda usar un venv en linux. Hay formas de usarlo sin tener que andar activando el venv, pero me da pereza explicarlo ahora.
|
|
||||||
|
|
||||||
python email-processor.py
|
python email-processor.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## El script / The script:
|
||||||
|
|
||||||
El Script hará las siguientes cosas:
|
- Conecta al servidor IMAP / Connects to IMAP server.
|
||||||
|
- Revisa mensajes en INBOX / Checks INBOX messages.
|
||||||
|
- Valida dominio y asunto / Validates domain and subject.
|
||||||
|
- Filtra spam / Filters spam.
|
||||||
|
- Exporta comentarios / Exports comments.
|
||||||
|
- Integra en Hugo o WordPress / Integrates with Hugo or WordPress.
|
||||||
|
- Borra mensajes procesados / Deletes processed messages.
|
||||||
|
|
||||||
Se conectará al servidor de correo
|
## ⚠️ Advertencia / Warning
|
||||||
De la bandeja selecionada (INBOX por defecto) revisará uno por uno los mensajes
|
|
||||||
Obtiene el asunto (corresponde al titulo de la página y tambien al directorio local de hugo)
|
|
||||||
Filtra que el dominio de la URL corresponda al del sitio, registrado en el .env (evita spam)
|
|
||||||
Obtiene remitente (se usará para identificar al comentarista)
|
|
||||||
Obtiene el mensaje y depura el HTML con el fin de obtener una versión mas simple y libre de posibles scripts indeseados.
|
|
||||||
Valida si el mensaje contiene alguna de las palabras de IGNORE_KEYWORDSy si no es el caso, continua el flujo
|
|
||||||
Si esta activo SAVE_MARKDOWN guardara un fragmento por mensaje
|
|
||||||
Si esta actuvo SAVE_XML guardará fragmentos para RSS en XML
|
|
||||||
Si esta activo SEND_WEBHOOK enviará el comentario al webhook de wordpress. Recuerda que tienes que haber configurado el secreto entre ambos.
|
|
||||||
Si esta activo SAVE_HTML guardara fragmentos HTML por mensajes
|
|
||||||
Si esta activo APPEND_HUGO convertirá el contenido HTML a Markdown y buscará en los directorios especificados en busca del post deducido de la URL. en caso de encontrarlo, agregara el comentario al final del post.
|
|
||||||
Borra los mensajes procesados
|
|
||||||
Cierra la sesion IMAP
|
|
||||||
|
|
||||||
El resultado es que se integraran los comentarios en las entradas y estos se cargaran la proxima vez que actualices tu sitio.
|
Publicar tu correo puede exponerte a spam / Publishing your email may expose you to spam.
|
||||||
|
|
||||||
|
Se recomienda usar una cuenta dedicada / Use a dedicated account.
|
||||||
|
|
||||||
|
Gmail puede funcionar con claves de aplicación / Gmail may work with app passwords.
|
||||||
|
|
||||||
|
## 📚 Recursos / Resources
|
||||||
|
[Repositorio principal / Main repo](https://git.interlan.ec/Drk0027/mail-comment)
|
||||||
|
|
||||||
|
[Funciones WordPress / WordPress functions](https://git.interlan.ec/Drk0027/mail-comment/src/branch/main/functions.php)
|
||||||
|
|
||||||
|
[Delta Chat Providers](https://providers.delta.chat/)
|
||||||
|
|
||||||
|
[Entrada en el blog/ Blog Entry](https://interlan.ec/blog/2026/01/16/comentarios-en-sitios-estaticos/)
|
||||||
|
|
||||||
|
📌 Estado / Status
|
||||||
|
Prototipo en desarrollo / Prototype in development.
|
||||||
|
Pruebas con Hugo (QuickStart) y flujo básico de WordPress / Tested with Hugo (QuickStart) and basic WordPress flow.
|
||||||
|
|
||||||
|
## 📌 Autoría y versión
|
||||||
|
|
||||||
|
- Autor: ([Drk0027](https://interlan.ec/portafolio-de-drk0027/))
|
||||||
|
- Versión: 0.1.0 (prototipo inicial)
|
||||||
|
- Licencia: MIT
|
||||||
|
|
||||||
|
## 🤝 Contribuciones por correo
|
||||||
|
|
||||||
|
Este proyecto no acepta pull requests en línea.
|
||||||
|
Si deseas contribuir:
|
||||||
|
|
||||||
|
1. Haz tus cambios en una rama local.
|
||||||
|
2. Genera un parche con:
|
||||||
|
```bash
|
||||||
|
git format-patch origin/main
|
||||||
|
Envía el parche por correo a: drk0027@interlan.ec
|
||||||
|
|
||||||
|
El autor revisará y aplicará el parche si es aceptado.
|
||||||
|
|
||||||
|
Nota: recuerda incluir una descripción clara en el asunto del correo.
|
||||||
Reference in New Issue
Block a user