[EN] Developing ‘Beneath the surface 🌊’
The idea
The first thing that came to mind was “how can I develop a page that I can leave as a reference for those who want to contact me in a professional setting?” and “through what medium can I share those ideas, small works or personal experiences that I believe could be useful for other professionals in my field?”. Well, there are many options around (social media, podcasts, TikTok, etc.). This first decision was not difficult, as I am not particularly characterized by my charisma on social networks, so I decided to opt for writing a blog. However, here the decision-making process did get a bit complicated, as there are many platforms available: Wordpress, Netlify, Gitlab pages, Medium, among others. Each one offers different advantages and potential, but my decision was based above all on the familiarity of use of the Github and Quarto platforms. I decided on Github pages.
Github pages
Github Pages is a free static website hosting service that allows you to publish HTML content directly from a GitHub repository. This platform offers multiple advantages:
It’s free!: You don’t need to pay for a web hosting service, just have a (free) GitHub account.
Easy to use: Uploading your HTML, CSS, and JavaScript files to GitHub is very simple.
Direct integration with GitHub: This becomes VERY important if you already use GitHub (as was my case) for your code projects.
Versioning: GitHub Pages keeps a history of all the changes you make to your website, so if something goes wrong you can always go back to a previous version of your repository (page).
Secure: GitHub Pages uses HTTPS to protect your website.
Fast: For a few years now, Microsoft has bought GitHub and therefore its services use an extensive global network of servers to deliver your website to users around the world.
Scalable: GitHub Pages can handle any amount of traffic, so your website can grow smoothly. Although a personal/professional blog is not expected to have very high traffic peaks, it is always good to know that this support exists.
SEO optimized: GitHub Pages is optimized for search engines, which will help your website appear in the results of major web search engines.
In the end, Github pages was the hosting option that I found most attractive. However, there are multiple ways to upload content, from different development platforms that involve the use of programming languages (e.g. Javascript) or markup, such as markdown or Quarto. Once again, my historical experience weighed more and I decided to use Quarto.
Quarto
Quarto is an open-source scientific document publishing platform developed by the POSIT (formerly RStudio) team. It is based on the R Markdown format and extends it with new features and functionalities to create richer and more interactive documents. It implements a more powerful preprocessing system than R Markdown and supports additional programming languages such as Python and Julia, expanding the possibilities for analysis and visualization.
For the past few years, I have been using Quarto not only for writing simple R reports, but also for the complete composition of scientific articles (one of them with a format submitted directly from the .docx output obtained in Quarto), as well as the development of interactive websites through the Quarto-Shiny duo.
The content
I Didn’t Have to Start from Scratch. Fortunately, there are many resources available online, but I will briefly summarize the main links I used:
- Create the website hosted on Github pages, prepare it for content management with Quarto and to work from RStudio: The first steps to follow are very well explained in the video by Melissa Van Bussel (link). Highly recommended, although it assumes that we know how to handle Git-bash and that we have a token well configured for our PC. I will put these last details at the end of this article.
Establish an outline of what we are going to publish: Once we have successfully configured our website, it is time to take pen and paper and outline what content we want to share and what the logic will be for organizing that content into sections. While this part is very personal, since it will not be the same to diagram a page that only aims to serve as a professional reference (that is, an interactive resume) to that of a freelancer who wants to show their main projects and/or services offered, you don’t need to start from scratch either. You can review examples of pages from other creators (researchers, reporters, bloggers, graphic artists, etc.) and be inspired by their designs. Also, you can review examples of page structures that use Github pages (link). Remember, everything must ALWAYS start with the type of content you plan to place.
Start writing: OK, this is not a scientific article and there is much more freedom to fill in the different sections; however, always remember to take into account the basic writing criteria (from general to specific), be clear and careful when choosing the type of language (based on the type of audience you expect to read you) and, once again, review examples. Of course, these days AI text generation platforms can be of great help, but we should not delegate the entire burden (i.e. no copy-paste) to them without first reading and corroborating the information they return to us. At this point, the following articles were very useful to me:
Create your website with Quarto: complete tutorial and template link: https://www.marvinschmitt.com/blog/website-tutorial-quarto/.
Creating your personal website with Quarto link: https://ucsb-meds.github.io/creating-quarto-websites/.
Creating a website link: https://quarto.org/docs/websites/.
Establish an order: Once we have finished and published a first article, everything will be simpler in technical terms since you will discover that there are multiple reference sources available.
[ES] Desarrollando ‘Beneath the surface 🌊’
La idea
Lo primero que llegó a mi mente fue «¿de qué manera puedo desarrollar una página en que pueda dejar como referencia para aquellos que quisieran contactar conmigo en un ambiente profesional?» y «¿desde qué medio puedo compartir aquellas ideas, pequeños trabajos o experiencias personales que creo que podrían resultar de utilidad para otros profesionales en mi rubro?». Bueno, existen muchas opciones alrededor (redes sociales, podcast, TikTok, etc.). Esta primera decisión no fue difícil, pues no me caracterizo particularmente por mi carisma en redes, así que decidí optar por escribir un blog. Sin embargo, aquí la toma de decisiones sí se complicó un poco, pues existen muchas plataformas disponibles: Wordpress, Netlify, Gitlab pages, Medium, entre others. Cada una plantea ventajas y potencialidades distintas, pero mi decisión se basó sobre todo en la familiaridad de uso de las plataformas Github y Quarto. Me decidí por Github pages.
Github pages
Github pages es un servicio gratuito de alojamiento de sitios web estáticos que permite publicar contenido HTML directamente desde un repositorio de GitHub. Esta plataforma ofrece múltiples ventajas:
Gratuito: No necesitas pagar por un servicio de alojamiento web, solo tener una cuenta de GitHub (gratuita).
Fácil de usar: Subir tus archivos HTML, CSS y JavaScript a GitHub es muy sencillo.
Integración directa con GitHub: Esto se hace MUY importante si ya usas GitHub (como fue mi caso) para tus proyectos de código.
Versionado: GitHub Pages guarda un historial de todos los cambios que realices en tu sitio web, por lo que si algo sale mal siempre puedes volver a una versión anterior de tu repositorio (página).
Seguro: GitHub Pages utiliza HTTPS para proteger tu sitio web.
Rápido: Desde hace unos años, Microsoft compró GitHub y por tanto sus servicios utilizan una extensa red global de servidores para entregar tu sitio web a los usuarios de todo el mundo.
Escalable: GitHub Pages puede manejar cualquier cantidad de tráfico, por lo que tu sitio web puede crecer sin problemas. Aunque de un blog personal/profesional no se espera tener picos de tráfico muy altos, siempre es bueno saber que existe este respaldo.
Optimizado para SEO: GitHub Pages está optimizado para los motores de búsqueda, lo que ayudará a que nuestro sitio web aparezca en los resultados de los principales buscadores web.
Al final, Github pages fue la opción de alojamiento que me resultó más atractiva. Sin embargo, existen múltiples maneras de subir contenido, desde diferentes plataformas de desarrollo que involucran el uso de lenguajes de programación (e.g. Javascript) o de marcado, como markdown o Quarto. Una vez más, mi experiencia histórica pesó más y me decanté por el uso de Quarto.
Quarto
Quarto es una plataforma de publicación de documentos científicos de código abierto desarrollada por el equipo de POSIT (ex RStudio). Se basa en el formato R Markdown y lo amplía con nuevas características y funcionalidades para crear documentos más ricos e interactivos. Implementa un sistema de preprocesamiento más potente que R Markdown y soporta lenguajes de programación adicionales como Python y Julia, ampliando las posibilidades de análisis y visualización.
Desde hace unos pocos años, he venido utilizando Quarto no solo para la redacción de reportes sencillos en R, sino inclusive para la composición completa de artículos científicos (uno de ellos con formato sometido directamente desde la salida en .docx obtenida en Quarto), así como el desarrollo de webs interactivas a través de la dupla Quarto-Shiny.
El contenido
No tuve que empezar desde cero. Afortunadamente, hay mucho material allá afuera, pero resumiré brevemente los principales links que utilicé:
- Crear la website alojada en Github pages, preparaela para el manejo de contenido con Quarto y para trabajar desde RStudio: Los primeros pasos a seguir están muy bien explicados en el vídeo de Melissa Van Bussel (link). Muy recomendable, aunque parte bajo el supuesto de que conocemos cómo manejar Git-bash y de que tenemos bien configurado un token para nuestra PC. Estos últimos detalles los colocaré al final de este artículo.
Establecer un esquema de lo que vamos a publicar. Una vez que hayamos logrado configurar correctamente nuestra web, sigue el turno de tomar lápiz y papel y esquematizar qué contenido deseamos compartir y cuál será la lógica para ordenar dicho contenido en secciones. Si bien esta parte es muy personal, ya que no será lo mismo diagramar una página que solo tiene como objetivo servir de referencia profesional (es decir, un CV interactivo) a la de un freelancer que desea mostrar sus principales proyectos y/o servicios ofrecidos, no necesitas ir desde cero tampoco. Puedes revisar ejemplos de páginas de otros creadores (investigadores, reporteros, bloggers, artistas gráficos, etc.) e inspirarte en sus diseños. Así también, puedes revisar ejemplos de estructuras de páginas que usan Github pages (link). Recuerda, todo debe partir SIEMPRE del tipo de contenido que planeas colocar.
Empezar a escribir. OK, esto no es un artículo científico y hay mucha más libertad para rellenar las distintas secciones; no obstante, recuerda siempre tener en cuenta los criterios básicos de redacción (de lo general a lo específico), ser claro y cuidadoso al elegir el tipo de lenguaje (con base en el tipo de público que esperas que te lea) y, una vez más, revisar ejemplos. Por supuesto, en estos días las plataformas de IA para generación de texto pueden resultar de gran ayuda, pero no debemos delegarles toda la carga (i.e. nada de copiar-pegar) sin antes leer corroborar la información que nos devuelven. En este punto, me fueron de mucha utilidad los siguientes artículos:
Establecer un orden. Una vez que hayamos culminado y publicado un primer artículo, todo irá siendo más simple en términos técnicos ya que descubrirás que existen múltiples fuentes de referencia disponibles.