Skip to content

Conversión del sitio de Apuntes a MkDocs

Migración del motor de apuntes de Ruby/Jekyll a Python/MkDocs.

Procedimiento

  1. Renombro el antiguo repositorio construido con Jekyll de eduardofilo.github.io a eduardofilo.jekyll para dejar libre el repositorio que contendrá el nuevo sitio.
  2. Creo directorio:
    $ mkdir ~/git/eduardofilo.mkdocs
    $ cd ~/git/eduardofilo.mkdocs
    
  3. Creo entorno Python3 con pipenv:
    $ pipenv install --three
    
  4. Instalo mkdocs, el tema Material y algunas extensiones:
    $ pipenv install mkdocs pygments mkdocs-material
    
  5. Instalo versión beta de módulo pyyaml por un aviso de seguridad que da GitHub sobre la versión 3.13 que se instala normalmente. Para ello añado lo siguiente al fichero Pipfile en la sección [packages]. Tras ello ejecuto pipenv install:
    pyyaml = ">=4.2b1"
    
  6. Arranco shell en el entorno:
    $ pipenv shell
    
  7. Creo el proyecto mkdocs desde el directorio anterior:
    $ cd ..
    $ mkdocs new eduardofilo.mkdocs
    $ cd eduardofilo.mkdocs
    
  8. Copio los directorios con los contenidos del sitio Jekyll (cursos, desarrollo, images, proyectos, sistemas y varios) al directorio docs.
  9. Configuro el fichero mkdocs.yml con el siguiente contenido:
    # Project information
    site_name: Apuntes de eduardofilo
    site_description: Apuntes varios sobre algunas de las cosas que necesito recordar, principalmente sobre Desarrollo y         Sistemas.
    site_author: Eduardo Moreno Lamana
    
    # Repository
    repo_name: 'eduardofilo.mkdocs'
    repo_url: https://github.com/eduardofilo/eduardofilo.mkdocs
    
    # Configuration
    use_directory_urls: false
    plugins:
        - search:
            lang: ['es']
    theme:
        name: material
        logo: 'images/eduardofilo.png'
        language: es
        feature:
            tabs: true
        palette:
            primary: 'deep orange'
            accent: 'amber'
    
    
    # Customization
    extra:
        social:
            - type: github-alt
              link: https://github.com/eduardofilo
            - type: twitter
              link: https://twitter.com/eduardofilo
            - type: linkedin
              link: https://linkedin.com/in/edumoreno/
            - type: tumblr
              link: https://eduardofilo.es
            - type: youtube
              link: https://www.youtube.com/c/EduardoMorenoLamana
        search:
            language: 'es'
        manifest: 'manifest.webmanifest'
    
    # Extensions
    markdown_extensions:
        - codehilite:
            linenums: true
        - toc:
            permalink: True
        - admonition
    
  10. Copio todos los ficheros del directorio _posts de Jekyll al directorio docs.
  11. Modifico cada uno de los posts que allí hay de la siguiente manera:
    1. Retiro los delimitadores del YAML, es decir los tres guiones que hay al principio y al final del bloque.
    2. Retiro las propiedad layout y published y añado una llamada summary.
  12. Genero estructura de navegación en bloque nav: al final de mkdocs.yml
  13. Creo fichero CNAME dentro del directorio docs con el nombre del dominio personalizado.
  14. Creo repositorio en GitHub con nombre eduardofilo.github.io.
  15. Creo copia de trabajo del repsitorio anterior:
    $ cd ~/git
    $ git clone git@github.com:eduardofilo/eduardofilo.github.io.git
    
  16. Finalmente publico el sitio ejecutando el siguiente comando desde el directorio de trabajo del repositorio anterior (hay que recordar que para que funcione el comando mkdocs hay que haber iniciado el entorno virtual antes con pipenv shell desde el directorio ~/git/eduardofilo.mkdocs):
    $ cd ~/git/eduardofilo.github.io
    $ mkdocs gh-deploy --config-file ../eduardofilo.mkdocs/mkdocs.yml --remote-branch master
    

Falta crear un RSS con el feed que generaba Jekyll antiguamente.

Enlaces documentación