Pelican est un outil Python incroyablement bien construit pour créer des sites statiques.
Full Stack Python est généré avec les modèles Pelican, Jinja2 et Markdown. Ce site est déployé sur Amazon S3 et gère actuellement plus de cent mille lecteurs par mois. Il n'y a jamais de problèmes de mise à l'échelle car un site statique est pré-généré avant le déploiement et un serveur Web répond simplement avec des fichiers existants plutôt que d'exécuter du code sur le serveur pendant le cycle requête-réponse HTTP.
Dans ce didacticiel, vous apprendrez à créer votre propre site Web statique à partir de zéro en utilisant Pelican.
Notre site statique simple aura des pages qui ressemblent à la capture d'écran ci-dessus, mais l'ensemble du site peut être facilement personnalisé et étendu avec votre propre conception et contenu.
Nos outils
Ce tutoriel devrait fonctionner avec Python 2 ou 3, mais Python 3 est fortement recommandé pour toutes les nouvelles applications. J'ai utilisé Python 3.6.1 pour écrire ce post. En plus de Python, tout au long de ce didacticiel, nous utiliserons également les dépendances d'application suivantes :
- Générateur de site Pelicanstatic, version 3.7.1
- Bibliothèque d'analyse Markdown pour gérer Markdown comme format d'entrée de contenu, version 2.6.8
- Jinja2, un moteur de template Python, version 2.9.6
- pip et virtualenv, qui sont fournis avec Python 3, pour installer et isoler les bibliothèques Pelican, Markdown et Jinja2 de n'importe lequel de vos autres projets Python
Si vous avez besoin d'aide pour configurer votre environnement de développement, consultez ce guide pour configurer Python 3 et Flask sur Ubuntu 16.04 LTS
Tout le code de cet article de blog est disponible en open source sous la licence MIT sur GitHub sous le répertoiregenerating-static-websites-pelican-jinja2-markdown du référentiel blog-code-examples. Utilisez et abusez du code source comme vous le souhaitez pour vos propres applications .
Installer les bibliothèques Pelican et Markdown
Commencez par créer un nouvel environnement virtuel pour votre projet. Mon virtualenvis nommé staticsite mais vous pouvez nommer le vôtre en fonction du projet que vous créez.
python3 -m venv staticsite
Activez l'environnement virtuel.
source staticsite/bin/activate
Le virtualenv ajoutera son nom à votre invite de commande lorsqu'il sera activé.
Installez les dépendances appropriées après l'activation de votre virtualenv. Utilisez le pip pour installer Pelican et Markdown, qui installeront également Jinja2 car Pelican le spécifie comme dépendance.
pip install pelican==3.7.1 markdown==2.6.8
Exécutez le pip commande et une fois que tout est installé, vous devriez voir une sortie similaire au message suivant "Installé avec succès".
Installing collected packages: pygments, pytz, six, feedgenerator, blinker, unidecode, MarkupSafe, jinja2, python-dateutil, docutils, pelican, markdown Running setup.py install for feedgenerator ... done Running setup.py install for blinker ... done Running setup.py install for MarkupSafe ... done Running setup.py install for markdown ... done Successfully installed MarkupSafe-1.0 blinker-1.4 docutils-0.13.1 feedgenerator-1.9 jinja2-2.9.6 markdown-2.6.8 pelican-3.7.1 pygments-2.2.0 python-dateutil-2.6.0 pytz-2017.2 six-1.10.0 unidecode-0.4.20
Maintenant que nos dépendances sont installées dans l'environnement virtuel, nous pouvons commencer à construire notre site statique.
Générer un site de base
Créez un nouveau répertoire pour stocker votre projet. Mon site contiendra certains de mes artistes de synthwave rétro préférés à titre d'exemples, mais bien sûr, votre site peut contenir tous les sujets que vous souhaitez.
Accédez au répertoire du projet après l'avoir créé.
mkdir retrosynth cd retrosynth
Exécutez le pelican-quickstart commande dans le nouveau répertoire du projet.
(staticsite) $ pelican-quickstart
Le script de démarrage rapide posera un tas de questions. Suivez les réponses ci-dessous ou modifiez-les pour votre propre nom de site et la configuration souhaitée.
Welcome to pelican-quickstart v3.7.1. This script will help you create a new Pelican-based website. Please answer the following questions so this script can generate the files needed by Pelican. > Where do you want to create your new web site? [.] > What will be the title of this web site? RetroSynthwave > Who will be the author of this web site? Matt Makai > What will be the default language of this web site? [en] > Do you want to specify a URL prefix? e.g., http://example.com (Y/n) n > Do you want to enable article pagination? (Y/n) n > What is your time zone? [Europe/Paris] America/New_York > Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n)y > Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) y > Do you want to upload your website using FTP? (y/N) n > Do you want to upload your website using SSH? (y/N) n > Do you want to upload your website using Dropbox? (y/N) n > Do you want to upload your website using S3? (y/N) y > What is the name of your S3 bucket? [my_s3_bucket] > Do you want to upload your website using Rackspace Cloud Files? (y/N) n > Do you want to upload your website using GitHub Pages? (y/N) n Done. Your new project is available at /Users/matt/devel/py/retrosynth (staticsite) $
Que venons-nous de créer à l'aide du script de démarrage rapide de Pelican ? Découvrez les nouveaux fichiers dans le répertoire.
(staticsite) $ ls Makefile develop_server.sh pelicanconf.py content fabfile.py publishconf.py
Le démarrage rapide a créé cinq fichiers et un nouveau répertoire :
Makefile:makecommandez des tâches pratiques pour des opérations courantes telles que l'exécution d'un serveur de développement, la création d'un site et le nettoyage de fichiers de construction superflusfabfile.py:Un fichier Fabric qui a certains des mêmes types de commandes que leMakefile. Fabric est une merveilleuse bibliothèque de codes, mais pour l'instant, je recommande d'ignorer le fichier Fabric, car malheureusement, Fabric ne prend pas encore en charge Python 3.develop_server.sh:script shell pour lancer le serveur de développementpelicanconf.py:fichier de paramètres pour votre projet Pelican. Si vous êtes habitué aux versions antérieures de Pelican, ce fichier s'appelait plutôtsettings.pypublishconf.py:un autre fichier de paramètres (optionnel) qui peut être considéré comme un fichier de paramètres de "production" lorsque vous dépassez la phase de développement et que vous souhaitez déployer votre sitecontent:emplacement pour vos fichiers de balisage, qui doivent être stockés souspagesetpostsrépertoires
Nous pouvons utiliser ces fichiers comme base pour notre nouveau site statique. Voyons à quoi ça ressemble par défaut en l'exécutant via le devserver tâche dans le Makefile.
make devserver
Le serveur de développement Pelican commencera à servir votre site avec le processus adaemon. Accédez à localhost:8000 dans votre navigateur Web et vous verrez la première version de votre site statique.
Que faire si vous n'avez pas make installé sur votre système ? Changez en output répertoire et utilisez le python -m http.server commande pour utiliser le serveur HTTP Python 3 intégré pour vos fichiers générés.
Lorsque vous voulez tuer le serveur de développement, recherchez un fichier nommé pelican.pid sous votre répertoire de projet. Le pelican.pid Le fichier est créé par Pelican et contient l'ID de processus de votre serveur de développement.
(staticsite) $ cat pelican.pid 1365
Utilisez le ps et grep commandes pour visualiser le processus puis arrêter le processus avec le kill commande comme suit. N'oubliez pas que votre ID de processus sera presque définitivement différent du 1365 ID pour mon processus.
Tuez le serveur de développement maintenant afin que nous puissions utiliser différentes commandes pour servir notre site après avoir créé notre contenu initial.
(staticsite) $ ps -A | grep 1365 1365 ttys003 0:01.43 /Library/Frameworks/Python.framework/Versions/3.6/Resources/Python.app/Contents/MacOS/Python /Users/matt/Envs/staticsite/bin/pelican --debug --autoreload -r /Users/matt/devel/py/retrosynth/content -o /Users/matt/devel/py/retrosynth/output -s /Users/matt/devel/py/retrosynth/pelicanconf.py 1411 ttys003 0:00.00 grep 1365 (staticsite) $ kill 1365 (staticsite) $ ps -A | grep 1365 1413 ttys003 0:00.00 grep 1365
C'est à vous de décider si vous souhaitez utiliser ou non le serveur de développement lors de la création de votre site. Chaque fois que je veux voir mes modifications pour Full Stack Python, je régénère le site en utilisant mon propre Makefile qui enveloppe le pelican commande. Le python -m http.server La commande sert constamment les modifications de chaque build.
Très bien, maintenant que nous avons nos fichiers de démarrage, nous pouvons commencer à créer du contenu initial.
Écrire du contenu
Pelican peut accepter les fichiers Markdown et reStructureTextmarkup en entrée.
Créez un nouveau sous-répertoire sous le content nommé posts . Changez en posts annuaire. Créez un nouveau fichier nommé gunship.markdown avec le contenu suivant.
title: Gunship slug: gunship category: bands date: 2017-06-09 modified: 2017-06-09 [Gunship](https://www.gunshipmusic.com/) is a *retro synthwave* artist out of the UK. [Revel in Your Time](https://www.youtube.com/watch?v=uYRZV8dV10w), [Tech Noir](https://www.youtube.com/watch?v=-nC5TBv3sfU), [Fly for Your Life](https://www.youtube.com/watch?v=Jv1ZN8c4_Gs) and [The Mountain](https://www.youtube.com/watch?v=-HYRTJr8EyA) are all quality songs by Gunship. Check out those amazing music videos! Also take a look at other retro synthwave artists such as [Trevor Something](https://trevorsomething.bandcamp.com/), [Droid Bishop](https://droidbishop.bandcamp.com/), [FM-84](https://fm84.bandcamp.com/) and [Daniel Deluxe](https://danieldeluxe.bandcamp.com/).
Notre make peut également nous aider à régénérer le site lorsque des modifications se produisent si nous choisissons de ne pas utiliser le serveur de développement.
Nous avons utilisé le devserver tâche plus tôt, mais quelles autres tâches sont disponibles pour nous via le Makefile ?
make
make devrait nous montrer toutes les tâches suivantes que nous pouvons exécuter.
Makefile for a pelican Web site Usage: make html (re)generate the web site make clean remove the generated files make regenerate regenerate files upon modification make publish generate using production settings make serve [PORT=8000] serve site at http://localhost:8000 make serve-global [SERVER=0.0.0.0] serve (as root) to :80 make devserver [PORT=8000] start/restart develop_server.sh make stopserver stop local server make ssh_upload upload the web site via SSH make rsync_upload upload the web site via rsync+ssh make dropbox_upload upload the web site via Dropbox make ftp_upload upload the web site via FTP make s3_upload upload the web site via S3 make cf_upload upload the web site via Cloud Files make github upload the web site via gh-pages Set the DEBUG variable to 1 to enable debugging, e.g. make DEBUG=1 html Set the RELATIVE variable to 1 to enable relative urls
Le html tâche est ce que nous recherchons pour invoquer le pelican commande en utilisant notre pelicanconf.py fichier de paramètres.
(staticsite) $ make html pelican /Users/matt/devel/py/retrosynth/content -o /Users/matt/devel/py/retrosynth/output -s /Users/matt/devel/py/retrosynth/pelicanconf.py Done: Processed 1 article, 0 drafts, 0 pages and 0 hidden pages in 0.14 seconds.
Notre site a été régénéré et placé dans le output répertoire.
Si vous avez utilisé le make devserver commande plus tôt puis changez en output et essayez le serveur HTTP intégré de Python avec la commande suivante.
cd output python -m http.server
Notre premier article dans toute sa splendeur...
Vous pouvez modifier la liaison du port du serveur HTTP en ajoutant un nombre après la commande, si vous souhaitez servir plusieurs sites statiques à la fois ou si vous avez déjà une application liée au port 8000.
python -m http.server 8005
Notez que si vous utilisez Python 2, la commande de serveur HTTP équivalente est python -m SimpleHTTPServer .
Notre site a maintenant un contenu très basique. Nous pourrions étendre ce début à de nombreux autres articles et pages, mais apprenons à modifier la configuration du site.
Modifier la configuration du site
Le démarrage rapide de Pelican suppose un tas de défauts qui peuvent ou non s'appliquer à votre site. Ouvrez le pelicanconf.py fichier pour modifier certaines des valeurs par défaut.
Recherchez le TIMEZONE variable. S'il ne convient pas à votre emplacement, modifiez-le pour votre zone. Wikipédia a un tableau pratique des valeurs de fuseaux horaires valides.
Modifiez également le LINKS tuple pour inclure votre site (ou Full Stack Python !) au lieu d'inclure le lien "vous pouvez modifier ces liens". Changer la dernière ligne de LINKS il ressemble donc au tuple de tuples suivant.
# Blogroll
LINKS = (('Pelican', 'http://getpelican.com/'),
('Python.org', 'http://python.org/'),
('Jinja2', 'http://jinja.pocoo.org/'),
('Full Stack Python', 'https://www.fullstackpython.com/'),)
Au lieu d'utiliser le make html fichier, cette fois nous invoquerons le pelican commande directement depuis la ligne de commande. Il n'y a rien de mal avec le Makefile , mais c'est une bonne idée de se familiariser avec Pelican directement au lieu de se contenter de fichiers de construction.
pelican -s pelicanconf.py -o output content
Exécutez maintenant le serveur HTTP si vous ne l'avez pas déjà exécuté dans une autre fenêtre de terminal.
cd output python -m http.server
Revenez au navigateur et actualisez pour afficher la configuration mise à jour.
Que se passe-t-il lorsque nous cliquons sur le titre de l'article de blog ? Cela nous amène à une page très similaire avec l'URL localhost:8000/gunship.html.
D'accord, nous avons mis à jour certaines données de base à l'échelle du site, mais notre site aurait vraiment besoin d'un changement de peinture.
Modifier le thème du site
Changer le thème du site est vraiment l'endroit où vous pouvez transformer un blog standard en n'importe quel type de site que vous souhaitez créer. Bien que la configuration par défaut de Pelican crée un modèle de blog, vous n'avez pas besoin d'avoir une structure chronologique si elle ne convient pas à votre site Web.
Créez un nouveau répertoire sous votre répertoire de projet nommé theme . Dans theme créer un autre répertoire nommé templates .templates est l'endroit où nos modèles Jinja2 seront stockés et peuvent remplacer le thème par défaut.
Commencez par créer un fichier nommé base.html qui stockera le passe-partout utilisé par les modèles sur le site.
<!DOCTYPE html>
<html lang="en">
<head>
<title>{% block title %}{% endblock %}</title>
</head>
<body>
<div class="container">
{% block content %}{% endblock %}
</div>
</body>
</html>
Dans theme/templates créer un fichier nommé article.html qui aura un thème différent pour les articles de blog que le reste du site. Remplir article.html avec le balisage Jinja2 suivant.
{% extends "base.html" %}
{% block title %}{{ article.title }}{% endblock %}
{% block content %}
<div class="row">
<div class="col-md-8">
<h1>{{ article.title }}</h1>
<label>Posted on <strong>{{ article.date }}</strong></label>
{{ article.content }}
</div>
</div>
{% endblock %}
Ensuite, nous utiliserons un modèle Jinja2 pour remplacer le index.html par défaut page d'accueil. Encore une fois dans le theme/templates répertoire, créez un fichier nommé index.html avec le balisage suivant.
{% extends "base.html" %}
{% block title %}{{ SITENAME }}{% endblock %}
{% block content %}
<div class="row">
<div class="col-md-8">
<h1>{{ SITENAME }}</h1>
{% for article in articles %}
<h2><a href="/{{ article.slug }}.html">{{ article.title }}</a></h2>
<label>Posted on <strong>{{ article.date }}</strong></label>
{{ article.content|truncate(110) }}
{% else %}
No posts yet!
{% endfor %}
</div>
</div>
{% endblock %}
Régénérez le site et assurez-vous que vous le servez avec le serveur de développement ou le python -m http.server commande.
Assurez-vous d'utiliser le nouveau -t theme drapeau pour spécifier que les Jinja2templates dans le theme répertoire doit être appliqué au site.
pelican -s pelicanconf.py -o output -t theme content
Allez sur localhost:8000 et actualisez la page. Le style de la page principale est maintenant différent car il utilise le index.html thème.
Cliquez sur le titre du message Gunship. Cette page utilise le article.html modèle, même si c'est difficile à dire car aucun CSS n'est appliqué à la page.
Assez clairsemé ! Nous pouvons au moins ajouter le CSS Bootstrap au HTML pour aligner notre contenu.
Dans base.html , ajoutez la ligne suivante pour Bootstrap sous <title>{% block title %}{% endblock %}</title> et au dessus de </head> .
<!-- Latest compiled and minified Bootstrap CSS --> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
Régénérez le site et actualisez la page Gunship.
Eh bien, au moins, notre conception est passée de 1996 à 2001. Je suis sûr que vous pouvez faire beaucoup plus pour améliorer la conception de votre propre site.
Le nouveau base.html ne fournit pas encore beaucoup de thème, mais il offre au moins un nouveau départ pour des sites entièrement personnalisés.
Quelle est la prochaine ?
Vous avez généré votre premier site Web statique Pelican en utilisant Markdown et Jinja2. Des modifications supplémentaires peuvent être apportées aux modèles Jinja2 et au contenu contenu dans les fichiers Markdown.
Voulez-vous déployer votre nouveau site Web statique sur des pages GitHub ou un compartiment S3 ? Eh bien, c'est une histoire pour un autre tutoriel Python Full Stack...
Des questions? Faites-le moi savoir via un ticket de problème GitHub sur le référentiel Full Stack Python, sur Twitter@fullstackpythonou @mattmakai.
Vous voyez quelque chose qui ne va pas dans cet article de blog ? La source de cette page sur GitHuband soumet une pull request.
