gdocs2json

Overview

gdocs2json is a Google Apps Script add-on that extracts the entire content of a Google Doc along with its comments into a unified, structured JSON file.

Features

• Complete Export: Exports the full structured body, headers, footers, footnotes, and embedded objects (images) metadata.
• Reduced Export: Exports a simplified version containing plaintext body, plaintext footnotes, and embedded objects metadata.
• Comment Extraction: Retrieves active comments and their replies (excluding deleted ones) using the Google Drive API v3.
• Modern UI: An aesthetic glassmorphic dark-mode modal dialog embedded directly into Google Docs.
• Deployment Tools: Includes a Python helper script to automatically generate standard icons for Google Workspace Marketplace publishing.

Project Structure

• Code.gs: Core Google Apps Script handling document traversal, comment list retrieval, UI creation, and server-side logic.
• download.html: The HTML/JS client side for the user dialog with a modern dark theme and dynamic download triggers.
• appsscript.json: Manifest file defining the scopes, advanced services (Drive API, Docs API), and addon configuration.
• resize_icons.py: Python utility to resize a base icon into mandatory dimensions (32x32, 128x128, 220x140) for publishing.
• INSTRUCCIONES.md: Step-by-step setup guide (in Spanish) for personal container-bound scripts or domain-wide deployments.

Installation Guide

This document details the steps required to configure and use the document and comments export add-on privately (for personal use) or internally within a Google Workspace organization.

Method 1: Private / Personal Use (Container-bound Script)

This method is the fastest for individual users who want to use the add-on in a specific document without publishing it.

Step 1: Open the Apps Script Editor

1. Open the Google Docs document where you want to use the add-on.
2. In the top menu, go to Extensions > Apps Script.

Step 2: Copy the Project Files

1. In the Apps Script editor, replace the entire content of the default file Código.gs (or Code.gs) with the content of the Code.gs file from this repository. Rename the editor file to Code.gs if desired.
2. Click the + (Add a file) button next to "Files" and select HTML.
3. Name the new file download (the editor will add the .html extension automatically).
4. Replace the entire content of the newly created download.html file with the content of the download.html file from this repository.
5. Go to Project Settings (gear icon in the left sidebar) and check the option Show "appsscript.json" manifest file in editor.
6. Return to the Editor tab (code < > icon), open the appsscript.json file which is now visible, and replace all its content with the content of the appsscript.json file from this repository.
7. Save the project by clicking the disk icon (Save project).

Step 3: Enable Advanced Services (Alternative Manual Method)

NOTE: If you copied the appsscript.json file in Step 2, this step will already be automatically configured with the required services and scopes, and no manual action is needed.

If you prefer to add them manually via the interface:
1. In the left sidebar of the Apps Script editor, click the + button next to Services.
2. In the list of services:
* Look for Drive API and select it. Ensure the version is v3 (if prompted) and the identifier is Drive. Click Add.
* Click + (Services) again, look for Google Docs API, ensure the identifier is Docs, and click Add.

Step 4: Authorization and Execution

1. Return to your Google Docs document tab and reload the page.
2. A new menu will appear in the top bar called Document Exporter (or under Extensions > Add-ons).
3. Click on Document Exporter > Export to JSON....
4. Google will request security authorization. Click Continue.
5. Select your Google account.
6. On the "Google hasn't verified this app" warning screen, click Advanced.
7. Click Go to Document Exporter (unsafe).
8. Grant the required permissions by clicking Allow.
9. The exporter interface will open. Select the desired export method to start the download.

Method 2: Internal Deployment for an Organization (Google Workspace)

If you want the add-on to be available to multiple users in your Google Workspace domain without everyone having to manually copy the code, you must publish it as an internal organization add-on.

Prerequisites

• An admin or developer account in the Google Workspace console.
• Access to Google Cloud Console with permissions to create projects in the organization.

Step 1: Create a Standalone Script

1. Go to script.google.com with your organizational account.
2. Create a New project.
3. Copy and configure the Code.gs, download.html, and the manifest appsscript.json files as described in Method 1.

Step 2: Link to a Google Cloud Project (GCP)

1. In the Apps Script editor, go to Project Settings (gear icon).
2. Check the box Show "appsscript.json" manifest file in editor.
3. Go to Google Cloud Console.
4. Create a new GCP project specifically for this add-on.
5. Copy the Project number (available on the GCP project info dashboard).
6. Return to the Apps Script project settings, click Change project, and enter the GCP Project Number.

Step 3: Configure OAuth Consent Screen

1. In Google Cloud Console, go to APIs & Services > OAuth consent screen.
2. Select Internal as the User Type so that only accounts from your organization can access it.
3. Complete the required fields of the application profile.
4. In the Scopes section, manually add the permissions required by the script:
   • https://www.googleapis.com/auth/documents.currentonly (active document access)
   • https://www.googleapis.com/auth/drive.readonly (reading comments via Drive API)
   • https://www.googleapis.com/auth/documents (if using advanced Docs API)
5. Save and continue.

Step 4: Publish the Editor Add-on

1. In Google Cloud Console, go to APIs & Services > Library.
2. Search for and enable the Google Workspace Marketplace SDK API.
3. After enabling it, go to APIs & Services > Google Workspace Marketplace SDK > App Configuration.
4. Configure the editor add-on integration parameters:
   • Check the Google Docs add-on box.
   • In Apps Script project ID, enter the ID of your Apps Script script.
   • Define the script deployment version.
5. Go to the Store Listing tab within the Marketplace SDK:
   • Fill out the listing information (name, descriptions, screenshots, icons).
   • In the visibility section, make sure to select Private (only for domain users).
6. Click Publish.

Step 5: Installation by Users

Once published in the organization's Workspace Marketplace:

• Individual Installation: Domain users can go to a Google Docs document, select Extensions > Add-ons > Get add-ons, search for the application in the internal organization tab, and install it.
• Forced Installation (Admin Console): The Workspace administrator can go to the Google Admin console, search for the internally published application, and automatically force its installation for the entire organization or specific organizational units.

Descripción General

gdocs2json es un complemento de Google Apps Script que extrae todo el contenido de un documento de Google Docs y sus comentarios en un archivo JSON estructurado y unificado.

Características

• Exportación Completa: Exporta la estructura completa del cuerpo, encabezados, pies de página, notas al pie y metadatos de objetos incrustados (imágenes).
• Exportación Reducida: Exporta una versión simplificada con texto plano del cuerpo, notas al pie y metadatos de objetos incrustados.
• Extracción de Comentarios: Recupera los comentarios activos y sus respuestas (excluyendo los eliminados) a través de la API de Google Drive v3.
• Interfaz Moderna: Diálogo modal estético en modo oscuro integrado directamente en Google Docs.
• Herramientas de Despliegue: Incluye un script en Python para generar automáticamente los iconos requeridos para su publicación en Google Workspace Marketplace.

Estructura del Proyecto

• Code.gs: Código principal de Google Apps Script que maneja el recorrido del documento, obtención de comentarios, creación de la interfaz y la lógica del lado del servidor.
• download.html: Interfaz del cliente en HTML/JS con un tema oscuro moderno y controladores de descarga dinámica.
• appsscript.json: Archivo de manifiesto que define los permisos (scopes), servicios avanzados (Drive API, Docs API) y la configuración del complemento.
• resize_icons.py: Utilidad en Python para redimensionar un icono base a las dimensiones obligatorias (32x32, 128x128, 220x140) para la publicación.
• INSTRUCCIONES.md: Guía de configuración paso a paso (en español) para uso personal o despliegues organizacionales.

Guía de Configuración e Instalación

Este documento detalla los pasos necesarios para configurar y utilizar el complemento de exportación de documentos y comentarios de forma privada (para uso personal) o de forma interna dentro de una organización de Google Workspace.

Método 1: Uso Privado / Personal (Script Contenedor)

Este método es el más rápido para usuarios individuales que desean utilizar el complemento en un documento específico sin realizar publicaciones.

Paso 1: Abrir el Editor de Apps Script

1. Abra el documento de Google Docs donde desea utilizar el complemento.
2. En el menú superior, diríjase a Extensiones > Apps Script.

Paso 2: Copiar los Archivos del Proyecto

1. En el editor de Apps Script, reemplace todo el contenido del archivo predeterminado Código.gs con el contenido del archivo Code.gs de este repositorio. Renombre el archivo del editor a Code.gs si lo desea.
2. Haga clic en el botón + (Agregar un archivo) junto a "Archivos" y seleccione HTML.
3. Nombre al nuevo archivo download (el editor añadirá la extensión .html automáticamente).
4. Reemplace todo el contenido del archivo download.html recién creado con el contenido del archivo download.html de este repositorio.
5. Diríjase a la Configuración del proyecto (icono de engranaje en la barra lateral izquierda) y marque la opción Mostrar el archivo de manifiesto "appsscript.json" en el editor.
6. Regrese a la pestaña Editor (icono de código < >), abra el archivo appsscript.json que ahora es visible y reemplace todo su contenido con el contenido del archivo appsscript.json de este repositorio.
7. Guarde el proyecto haciendo clic en el icono del disco (Guardar proyecto).

Paso 3: Habilitar los Servicios Avanzados (Método Alternativo Manual)

NOTA: Si en el Paso 2 copió el archivo appsscript.json, este paso ya se habrá configurado automáticamente con los servicios y alcances necesarios y no requiere acción manual.

Si prefiere agregarlos manualmente a través de la interfaz:
1. En la barra lateral izquierda del editor de Apps Script, haga clic en el botón + junto a Servicios.
2. En la lista de servicios:
* Busque Drive API y selecciónelo. Asegúrese de que la versión sea la v3 (si se le solicita) y que el identificador sea Drive. Haga clic en Añadir.
* Haga clic nuevamente en + (Servicios), busque Google Docs API, verifique que el identificador sea Docs y haga clic en Añadir.

Paso 4: Autorización y Ejecución

1. Regrese a la pestaña de su documento de Google Docs y recargue la página.
2. Aparecerá un nuevo menú en la barra superior llamado Exportador de Documento (o bajo Extensiones > Complementos).
3. Haga clic en Exportador de Documento > Exportar a JSON....
4. Google solicitará autorización de seguridad. Haga clic en Continuar.
5. Seleccione su cuenta de Google.
6. En la pantalla de advertencia "Google no ha verificado esta aplicación", haga clic en Configuración avanzada.
7. Haga clic en Ir a Exportador a JSON (no seguro).
8. Conceda los permisos requeridos haciendo clic en Permitir.
9. Se abrirá la interfaz del exportador. Seleccione el método de exportación deseado para iniciar la descarga.

Método 2: Despliegue Interno para una Organización (Google Workspace)

Si desea que el complemento esté disponible para múltiples usuarios de su dominio de Google Workspace sin que cada uno deba copiar el código manualmente, debe publicarlo como un complemento interno de la organización.

Requisitos Previos

• Una cuenta de administrador o desarrollador en la consola de Google Workspace.
• Acceso a Google Cloud Console con permisos para crear proyectos en la organización.

Paso 1: Crear un Script Independiente

1. Acceda a script.google.com con su cuenta organizativa.
2. Cree un Nuevo proyecto.
3. Copie y configure los archivos Code.gs, download.html y el archivo de manifiesto appsscript.json tal como se describe en el Método 1.

Paso 2: Vincular a un Proyecto de Google Cloud (GCP)

1. En el editor de Apps Script, vaya a Configuración del proyecto (icono de engranaje).
2. Marque la casilla Mostrar el archivo de manifiesto "appsscript.json" en el editor.
3. Vaya a Google Cloud Console.
4. Cree un nuevo proyecto de GCP específico para este complemento.
5. Copie el Número de proyecto (disponible en el panel de información del proyecto de GCP).
6. Regrese a la configuración del proyecto de Apps Script, haga clic en Cambiar de proyecto e introduzca el Número del proyecto de GCP.

Paso 3: Configurar la Pantalla de Consentimiento OAuth

1. En Google Cloud Console, vaya a API y servicios > Pantalla de consentimiento de OAuth.
2. Seleccione Interno como el Tipo de usuario (User Type) para que solo las cuentas de su organización puedan acceder.
3. Complete los campos obligatorios del perfil de la aplicación.
4. En la sección Permisos (Scopes), agregue manualmente los permisos requeridos por el script:
   • https://www.googleapis.com/auth/documents.currentonly (acceso al documento activo)
   • https://www.googleapis.com/auth/drive.readonly (lectura de comentarios mediante Drive API)
   • https://www.googleapis.com/auth/documents (si se utiliza la API de Docs avanzada)
5. Guarde y continúe.

Paso 4: Publicar el Complemento de Editor

1. En Google Cloud Console, vaya a API y servicios > Biblioteca.
2. Busque e active la API Google Workspace Marketplace SDK.
3. Tras activarla, vaya a API y servicios > Google Workspace Marketplace SDK > Configuración.
4. Configure los parámetros de integración del complemento de editor:
   • Active la casilla Extensiones de Google Docs.
   • En ID de script del proyecto, introduzca el ID de su script de Apps Script.
   • Defina la versión de despliegue del script.
5. Vaya a la pestaña Publicar en App Store dentro del SDK de Marketplace:
   • Rellene la información de la ficha (nombre, descripciones, capturas de pantalla, iconos).
   • En la sección de visibilidad, asegúrese de seleccionar Privado (solo para usuarios del dominio).
6. Haga clic en Publicar.

Paso 5: Instalación por parte de los Usuarios

Una vez publicado en la Workspace Marketplace de la organización:

• Instalación Individual: Los usuarios del dominio pueden ir a un documento de Google Docs, seleccionar Extensiones > Complementos > Obtener complementos, buscar la aplicación en la pestaña interna de la organización e instalarla.
• Instalación Forzada (Consola de Administración): El administrador de Workspace puede ingresar a la consola de administración de Google, buscar la aplicación publicada internamente y forzar la instalación a toda la organización o a unidades organizativas específicas de forma automática.