pages rapides
vements to styling
Plus d’informations sur les raisons pour lesquelles nous avons abandonné ce projet sont ici.
fastpagesUne plateforme de blogs facile à utiliser, prenant en charge les blocs-notes Jupyter, les documents Word et Markdown.
fastpages utilise GitHub Actions pour simplifier le processus de création d'articles de blog Jekyll sur les pages GitHub à partir d'une variété de formats d'entrée.
fastpages offre les fonctionnalités suivantes :Voir ci-dessous pour une liste plus détaillée des fonctionnalités.
Voir le site de démonstration
fastpagesfastpages offre les fonctionnalités suivantes :Générez une copie de ce dépôt en cliquant sur ce lien. Assurez-vous de vous connecter à votre compte, sinon vous verrez une erreur 404. Nommez votre dépôt comme vous le souhaitez, sauf {votre nom d'utilisateur}.github.io.
GitHub Actions ouvrira automatiquement un PR sur votre nouveau référentiel environ 30 secondes après la création de la copie. Suivez les instructions de ce PR pour continuer.
Si vous ne voyez pas de PR, assurez-vous que les actions tierces sont activées dans votre organisation : Paramètres -> Actions -> Autorisations des actions -> Activer les actions locales et tierces pour ce référentiel.
Pour une présentation en direct des étapes de configuration (avec quelques conseils supplémentaires), consultez ce didacticiel vidéo sur la création d'un blog fastpages par Abdul Majed.
Read and Write et cochez Allow GitHub Actions to create and approve pull requests . 
Une fois que vous avez accordé les autorisations, accédez à l'onglet Actions en haut de la page d'accueil de votre référentiel, où une liste d'exécutions d'actions vous sera présentée. Cliquez d'abord sur l'exécution ayant échoué (l'élément avec le X rouge) :
Vous serez redirigé vers un écran où il y aura un bouton en haut à droite vous permettant de réexécuter les tâches.
Après cela, une pull request devrait apparaître.
_posts , _notebooks ou _word . Vous pouvez suivre des exemples de contenu dans ces dossiers dans ce référentiel expliquant comment structurer le contenu. La chose la plus importante à laquelle il faut prêter attention est la question préliminaire, qui est abordée plus en détail ci-dessous. De plus, vous pouvez ajouter des pages supplémentaires qui apparaîtront sur la barre de navigation de votre blog dans le répertoire _pages . Notez que le contenu du répertoire _word ne prend pas en charge les éléments préliminaires. Front Matter vous permet d'activer/désactiver diverses options pour chaque article de blog, ainsi que de transmettre des métadonnées à diverses fonctionnalités des pages rapides.
Dans un bloc-notes, les éléments préliminaires sont définis comme une cellule de démarque au début du bloc-notes avec le contenu suivant :
# "Title"
> "Awesome summary"
- toc: false
- branch: master
- badges: true
- comments: true
- categories: [ fastpages, jupyter ]
- image: images/some_folder/your_image.png
- hide: false
- search_exclude: true
- metadata_key1: metadata_value1
- metadata_key2: metadata_value2De même, dans un document markdown, le même élément initial serait défini comme ceci au début du document :
---
title : " My Title "
description : " Awesome description "
layout : post
toc : false
comments : true
image : images/some_folder/your_image.png
hide : false
search_exclude : true
categories : [fastpages, jupyter]
metadata_key1 : metadata_value1
metadata_key2 : metadata_value2
---Des métadonnées supplémentaires sont facultatives et vous permettent de définir des éléments de présentation personnalisés.
Notez que tout ce qui est défini en introduction doit être un YAML valide. Si vous ne fournissez pas de YAML valide, votre page pourrait ne pas s'afficher sur votre blog. Par exemple, si vous voulez un deux-points dans votre titre, vous devez l'échapper avec des guillemets comme ceci :
- title: "Deep learning: A tutorial"
Consultez ce tutoriel sur YAML pour plus d’informations.
Title par le titre souhaité et Awesome summary par le résumé souhaité.Remarque : Il est recommandé de placer ces valeurs entre guillemets doubles, afin de pouvoir échapper les deux-points et autres caractères susceptibles de perturber l'analyseur YAML.
fast_template générera automatiquement une table des matières pour vous basée sur les en-têtes de démarque ! Vous pouvez activer ou désactiver cette fonctionnalité en définissant toc: sur true ou false .Cette option fonctionne uniquement pour les ordinateurs portables
branch est utilisé pour afficher éventuellement un lien entre votre bloc-notes et Colab et GitHub dans votre article de blog. Il sera par défaut master si vous ne le spécifiez pas dans le bloc-notes.badges sur false . La valeur par défaut est truebadges: true , les quatre badges (GitHub, Binder, Deepnote, Colab) apparaîtront par défaut. Vous pouvez ajuster ces valeurs par défaut avec le paramètre default_badges dans les options de configuration à l'échelle du site. Si vous souhaitez uniquement masquer un badge sur une publication individuelle, vous pouvez définir la préface hide_{github,colab,binder,deepnote}_badge: true . Par exemple, si vous souhaitez masquer le badge Binder pour un bloc-notes individuel mais que vous souhaitez que les autres badges apparaissent, vous pouvez définir cela dans votre présentation :
- badges : true
- hide_binder_badge : truerequirements.txt avec les packages communs que vous utilisez pour tous vos blocs-notes à la racine de votre référentiel. Vous pouvez en savoir plus sur la documentation officielle de Binder.Vous pouvez avoir une liste de catégories séparées par des virgules entre crochets pour un article de blog, ce qui rendra l'article visible sur la page des balises du site de votre blog. Par exemple:
Dans un cahier :
# "My Title"
- categories: [fastpages, jupyter]
Dans un document démarque :
---
title: "My Title"
categories: [fastpages, jupyter]
---
Vous pouvez voir un aperçu de ce à quoi cela ressemble ici.
show_tags sur true ou false dans _config.yml : # Set this to true to display tags on each post
show_tags : true Les commentaires sur les articles de blog sont optimisés par Utterances, un moyen open source et sans publicité de mettre en œuvre des commentaires. Tous les commentaires sont stockés dans des numéros sur le dépôt GitHub de votre blog. Vous pouvez activer cette option en définissant comments sur true . La valeur par défaut est false .
Pour activer les commentaires avec les énoncés, vous devrez procéder comme suit :
Sur les sites de réseaux sociaux comme Twitter, un aperçu de l'image peut être automatiquement affiché avec votre URL. La spécification de l' image initiale fournit ces métadonnées aux sites de médias sociaux pour qu'ils restituent cette image pour vous. Vous pouvez définir cette valeur comme suit :
- image: images/diagram.png
Remarque : pour ce paramètre, vous ne pouvez référencer que les fichiers et dossiers image dans le dossier /images de votre dépôt.
Vous souhaiterez peut-être empêcher qu'un article de blog soit répertorié sur la page d'accueil, tout en conservant une URL publique que vous pouvez prévisualiser ou partager discrètement. Vous pouvez masquer un article de blog sur la page d'accueil en définissant le masque de hide sur true . Ceci est défini sur false par défaut.
Il est recommandé d'utiliser des permaliens afin de générer une URL prévisible pour les articles de blog masqués. Vous pouvez également définir le paramètre search_exclude sur true si vous ne souhaitez pas que les utilisateurs trouvent votre message caché dans une recherche.
Par défaut, les publications sont triées par date sur votre page d'accueil. Cependant, vous souhaiterez peut-être qu’un ou plusieurs articles de blog apparaissent toujours tout en haut de votre page d’accueil. En d’autres termes, vous souhaiterez peut-être que certains messages soient « épinglés » ou « collants ». Pour ce faire, spécifiez le sujet sticky_rank dans l'ordre dans lequel vous souhaitez que vos messages collants apparaissent. Les articles de blog qui ne définissent pas ce paramètre sont triés par défaut par date après les articles collants.
Par exemple, considérons ces trois articles de démarque (fonctionne également pour les cahiers).
2020-01-01-Post-One.md
---
title : Post One
sticky_rank : 1
--- 2020-02-01-Post-Two.md
---
title : Post Two
sticky_rank : 2
--- 2020-04-01-Post-Three.md
---
title : Post Three
--- Cependant, puisque sticky_rank est spécifié, les articles de blog seront d'abord triés par sticky_rank dans l'ordre croissant, puis par date dans l'ordre décroissant , donc l'ordre de ces articles apparaîtra comme suit :
Sans sticky_rank les publications ci-dessus seraient en fait triées dans l'ordre inverse en raison des dates associées à chaque publication.
Remarque : l'épinglage fonctionne également pour les blocs-notes :
# "My cool blog post"
> "Description of blog post"
- sticky_rank: 2
fastpages est livré avec une recherche par mot clé intégrée optimisée par lunr.js. Vous pouvez empêcher un article de blog ou une page d’apparaître dans les résultats de recherche en définissant le paramètre search_exclude sur false . Ceci est défini sur true par défaut.
Il est recommandé à chacun de personnaliser son site de blog en définissant des options de configuration à l'échelle du site . Ces options se trouvent dans /_config.yml . Vous trouverez ci-dessous une description des différentes options disponibles.
title : c'est le titre qui apparaît dans le coin supérieur gauche de l'en-tête de toutes vos pages.
description : cette description apparaîtra à divers endroits lorsqu'un aperçu de votre site sera généré (par exemple, sur les réseaux sociaux).
github_username : cela permet à votre site d'afficher un lien vers votre page GitHub dans le pied de page.
github_repo : cela permet à votre site d'afficher des liens vers votre référentiel pour diverses fonctionnalités telles que des liens vers GitHub, Colab et Deepnote pour les notebooks.
url : cela n'a pas besoin d'être modifié, sauf si vous disposez d'un domaine personnalisé. Remarque : omettez le / final de cette valeur.
baseurl : consultez les commentaires dans /_config.yml pour obtenir des instructions ("Instructions spéciales pour baseurl" sur la définition correcte de cette valeur. Si vous n'avez pas de domaine personnalisé, vous pouvez probablement ignorer cette option.
email : celui-ci est actuellement inutilisé. Ignorer.
twitter_username : crée un lien dans votre pied de page vers votre page Twitter.
use_math : définissez ceci sur true pour obtenir la prise en charge des équations mathématiques LaTeX. Cette option est désactivée par défaut car elle charge autrement du javascript dans chaque page qui ne peut pas être utilisée.
show_description : Ceci affiche une description sous le titre de vos articles de blog sur votre page d'accueil qui contient une liste de vos articles de blog. Défini sur true par défaut.
google_analytics : utilisez éventuellement un identifiant Google Analytics pour le suivi si vous le souhaitez.
show_image : si défini sur true, cela utilise le paramètre image dans le début de vos articles de blog pour afficher un aperçu de vos blogs, comme indiqué ci-dessous. Ceci est défini sur false par défaut. Lorsque show_image est défini sur true votre page d'accueil ressemblera à ceci :
show_tags : Vous pouvez activer ou désactiver l'affichage des balises sur vos articles de blog en définissant cette valeur sur false . Ceci est défini sur true par défaut, ce qui affiche les liens suivants pour les balises sur vos articles de blog comme ceci :
pagination : C'est le nombre maximum de posts à afficher sur chaque page de votre page d'accueil. Toutes les publications dépassant ce montant seront paginées sur une autre page. Celui-ci est défini sur 15 par défaut. Lorsque cela se déclenche, vous verrez la pagination en bas de votre page d'accueil apparaître comme ceci :
Remarque : si vous utilisez une ancienne version de fastpages, vous ne pouvez pas utiliser le processus de mise à niveau automatisé pour obtenir la pagination. Au lieu de cela, vous devez suivre ces étapes :
mv index.md index.html
Gemfile et Gemfile.lock à la racine de votre dépôt par les fichiers de ce dépôt._config.yml comme suit (regardez _config.yml pour un exemple) : gems :
- jekyll-paginate
paginate : 10
paginate_path : /page:num/Alternativement, vous pouvez copier toutes vos publications dans un référentiel nouvellement créé à partir du modèle fastpages.
default_badges : par défaut, les badges GitHub, Binder, Deepnote et Colab apparaîtront sur les articles de blog du bloc-notes. Vous pouvez ajuster ces valeurs par défaut en définissant la valeur appropriée dans default_badges sur false. Par exemple, si vous souhaitez désactiver les badges Binder par défaut, vous devez remplacer default_badges par ceci :
default_badges :
github : true
binder : false
deepnote : false
colab : true html_escape : cela vous permet d'activer ou de désactiver l'échappement du HTML dans divers composants des articles de blog. Pour le moment, vous ne pouvez activer cette option que pour le champ description de vos publications.
Ceci est défini sur false par défaut.
Vous pouvez ajuster la largeur de la page des fastpages sur différents appareils en éditant /_sass/minima/custom-variables.scss.
Voici les valeurs par défaut, qui peuvent être ajustées selon vos préférences :
// width of the content area
// can be set as "px" or "%"
$content-width : 1000 px ;
$on-palm : 800 px ;
$on-laptop : 1000 px ;
$on-medium : 1000 px ;
$on-large : 1200 px ;hypothes.is est une plateforme ouverte qui permet d'annoter et de mettre en évidence des pages, qui peuvent être publiques ou privées. Lorsque cette fonctionnalité est activée, les lecteurs de votre blog se verront présenter l'info-bulle suivante lors de la mise en surbrillance du texte :
Ceci est désactivé par défaut dans les pages rapides. Vous pouvez activer ou désactiver cela dans votre fichier _config.yml en définissant annotations sur true ou false :
# Set this to true to turn on annotations with hypothes.is
annotations : falseVous pouvez personnaliser hypothes.is en lisant ces options de configuration. C'est également une bonne idée de lire ces documents si vous souhaitez en faire plus avec hypothes.is. Cependant, avant d'essayer de personnaliser cette fonctionnalité, vous devez lire la section personnalisation des pages rapides pour connaître les mises en garde importantes.
Vous pouvez demander à vos lecteurs de s'abonner aux flux RSS. Il existe de nombreux services d'abonnement RSS disponibles sur Internet. Voici quelques exemples :
fastpages remplace la coloration syntaxique par défaut des minima avec le thème Dracula.
La mise en surbrillance par défaut dans les pages rapides ressemble à ceci :
Cependant, vous pouvez faire en sorte que la coloration syntaxique ressemble à ceci, si vous choisissez :
Si vous souhaitez revenir au thème clair ci-dessus, vous pouvez supprimer la ligne ci-dessous dans _sass/minima/custom-styles.scss
@import " minima/fastpages-dracula-highlight " ; Si vous n'aimez aucun de ces thèmes, vous pouvez ajouter votre propre CSS dans _sass/minima/custom-styles.scss . Voir personnalisation des fastpages pour plus de détails.
Cet article de blog décrit comment activer le mode sombre pour les pages rapides.
Les utilisateurs qui préfèrent utiliser le système de citation BibTeX peuvent le faire ; cela nécessite d'activer le plugin jekyll-scholar. Veuillez consulter les citations dans Fastpages via BibTeX et jekyll-scholar pour obtenir des instructions sur la mise en œuvre de cela.
Placez le commentaire #hide au début d'une cellule de code et il masquera à la fois l'entrée et la sortie de cette cellule.
Un commentaire #hide_input en haut de n'importe quelle cellule masquera uniquement l'entrée .
De plus, l'extension Jupyter hide input peut être utilisée pour masquer les entrées ou sorties de cellules, qui seront respectées par les fastpages.
Vous souhaiterez peut-être qu'une partie du code soit masquée dans un élément réduit que l'utilisateur peut développer, plutôt que de cacher complètement le code au lecteur.
#collapse en haut de la cellule de code.#collapse_show ou #collapse-show en haut de la cellule de code.#collapse_output ou #collapse-output en haut de la cellule de code.Dans une cellule de démarque de votre bloc-notes, utilisez les raccourcis de démarque suivants pour intégrer des cartes Twitter et des vidéos YouTube.
> youtube: https://youtu.be/your-link
> twitter: https://twitter.com/some-linkL'ajout de notes de bas de page dans des blocs-notes est un peu différent du démarque. Veuillez consulter le guide détaillé des notes de bas de page dans les blocs-notes.
Enregistrez votre bloc-notes avec la convention de dénomination YYYY-MM-DD-*. dans le dossier /_notebooks ou /_word de ce dépôt, respectivement. Par exemple 2020-01-28-My-First-Post.ipynb . Cette convention de dénomination est requise par Jekyll pour afficher votre article de blog.
Attention à bien nommer votre fichier ! Il est facile d’oublier le dernier tiret de YYYY-MM-DD- . De plus, le caractère qui suit immédiatement le tiret ne doit être qu’une lettre alphabétique. Voici des exemples de noms de fichiers valides :
2020-01-28-My-First-Post.ipynb
2012-09-12-how-to-write-a-blog.ipynb Si vous ne parvenez pas à nommer correctement votre fichier, fastpages tentera automatiquement de résoudre le problème en ajoutant la date de dernière modification de votre fichier à votre article de blog généré. Cependant, il est recommandé de nommer correctement vos fichiers vous-même pour plus de transparence.
Validez et envoyez vos fichiers vers GitHub dans la branche principale de votre référentiel.
GitHub convertira automatiquement vos fichiers en articles de blog. Le processus de conversion prendra environ 5 minutes . Vous pouvez cliquer sur l'onglet Actions de votre dépôt pour afficher les journaux de ce processus. Deux flux de travail seront déclenchés à chaque poussée que vous effectuerez vers votre branche principale : (1) « CI » et (2) « État des pages GH ». Les deux flux de travail doivent être complétés par une coche verte pour votre dernier commit avant la mise à jour de votre site.
Si vous le souhaitez, vous pouvez prévisualiser l'apparence de votre blog localement avant de vous engager sur GitHub. Consultez cette section pour un guide détaillé sur l’exécution de l’aperçu localement.
Si vous écrivez votre article de blog en markdown, enregistrez votre fichier .md dans le dossier /_posts avec la même convention de dénomination ( YYYY-MM-DD-*.md ) spécifiée pour les blocs-notes.
Enregistrez vos documents Microsoft Word dans le dossier /_word avec la même convention de dénomination ( YYYY-MM-DD-*.docx ) spécifiée pour les blocs-notes.
Remarque : le texte alternatif dans les documents Word n'est pas encore pris en charge par les pages rapides et rompra les liens vers les images.
fastpages ne dispose pas d'un moyen robuste pour spécifier les éléments préliminaires des documents Word. Pour le moment, vous ne pouvez spécifier le contenu global de tous les documents Word qu'en modifiant _action_files/word_front_matter.txt.
Pour spécifier une présentation unique par document Word, vous devrez convertir manuellement Word en fichiers markdown. Vous pouvez suivre les étapes de cet article de blog, qui vous expliquent comment utiliser pandoc pour effectuer la conversion. Remarque : Si vous souhaitez personnaliser votre article de blog généré par Word en markdown, assurez-vous de supprimer votre document Word du répertoire _word afin que votre fichier markdown ne soit pas écrasé !
Si votre principale méthode de rédaction d'articles de blog consiste à utiliser des documents Word et que vous envisagez de toujours modifier manuellement les fichiers markdown convertis à partir de Word, il est probablement préférable d'utiliser fast_template au lieu de fastpages.
Voir le guide de développement.
L'action fastpages vous permet de convertir des blocs-notes de /_notebooks et des documents Word des répertoires /_word de votre dépôt en fichiers de démarques d'articles de blog conformes à Jekyll situés dans /_posts . Remarque : Cette structure de répertoires est actuellement inflexible pour cette action, car elle est conçue pour être utilisée avec Jekyll.
Si vous êtes déjà suffisamment familier avec Jekyll et souhaitez utiliser cette automatisation dans votre propre thème, vous pouvez utiliser cette action GitHub en référençant fastai/fastpages@master comme suit :
...
uses : fastai/fastpages@master
...Un exemple illustratif de ce à quoi peut ressembler un flux de travail complet :
jobs :
build-site :
runs-on : ubuntu-latest
...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
...
- name : Jekyll build
uses : docker://jekyll/jekyll
with :
args : jekyll build
- name : Deploy
uses : peaceiris/actions-gh-pages@v3
if : github.event_name == 'push'
with :
deploy_key : ${{ secrets.SSH_DEPLOY_KEY }}
publish_branch : gh-pages
publish_dir : ./_siteNotez que cette action n'a aucune entrée requise et n'a aucune variable de sortie .
BOOL_SAVE_MARKDOWN : Soit « vrai » soit « faux ». S'il faut ou non valider les fichiers markdown convertis à partir de blocs-notes et de documents Word dans le répertoire _posts de votre dépôt. Ceci est utile pour le débogage. par défaut : fauxSSH_DEPLOY_KEY : une clé de déploiement ssh est requise si BOOL_SAVE_MARKDOWN = 'true'Voir les spécifications de l'API pour cette action dans action.yml
Les instructions détaillées sur la façon de personnaliser ce blog dépassent la portée de ce README. (Nous invitons quelqu'un de la communauté à rédiger un article de blog expliquant comment procéder dans ce dépôt !)
Veuillez consulter le guide de contribution.
Veuillez consulter le guide de mise à niveau.
_posts/ qui sont générés à partir de mes blocs-notes Jupyter ou de mes documents Word ? R : Le flux de travail GitHub Actions de ce dépôt convertit votre bloc-notes et vos documents Word en démarques à la volée avant de créer votre site, mais ne valide jamais ces fichiers de démarques intermédiaires dans ce dépôt. Ceci afin de vous éviter les désagréments liés à la désynchronisation constante de votre environnement local avec votre référentiel. Vous pouvez éventuellement voir ces fichiers de démarques intermédiaires en définissant les entrées BOOL_SAVE_MARKDOWN et SSH_DEPLOY_KEY sur l'action fastpages dans votre fichier .github/workflows/ci.yaml comme suit : ...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
with :
BOOL_SAVE_MARKDOWN : true
SSH_DEPLOY_KEY : ${{ secrets.SSH_DEPLOY_KEY }}
... Q : Puis-je utiliser fastpages pour les sites de documentation Jekyll ou pour des éléments qui ne sont pas des articles de blog Jekyll ? R : Pour le moment, fastpages est une solution très avisée qui ne fonctionne que pour les articles du blog Jekyll. Si vous souhaitez rédiger de la documentation pour votre module ou bibliothèque avec des notebooks Jupyter, nous vous suggérons d'utiliser fastai/nbdev qui est expressément conçu à cet effet.
Q : Quelle est la différence entre fast_template et fastpages ? Lequel dois-je utiliser ? R : Étant donné que fastpages est plus flexible et extensible, nous vous recommandons de l'utiliser dans la mesure du possible. fast_template peut être une meilleure option pour attirer des blogueurs qui n'ont aucune expertise technique et qui créeront uniquement des articles à l'aide de l'éditeur en ligne intégré de Github.
fastpages s'appuie sur le thème minima. Si vous souhaitez personnaliser le style ou la mise en page des pages rapides, vous pouvez trouver des instructions dans le README de minima. C'est une bonne idée de lire le contenu complet du README pour comprendre la structure des répertoires. De plus, c'est une bonne idée d'avoir une compréhension de base de Jekyll avant de personnaliser votre thème. Pour ceux qui découvrent Jekyll, la documentation officielle est un bon point de départ. Concrètement, vous pouvez remplacer le CSS dans les fastpages dans _sass/minima/custom-styles.scss . NOTEZ que la fonctionnalité "skins" de minima est actuellement incompatible avec les paramètres CSS de fastpages.
Si vous choisissez d'effectuer des personnalisations sur fastpages Il est possible que les personnalisations que vous effectuez entrent en collision avec les versions actuelles ou futures de fastpages et nous vous recommandons de le faire uniquement si vous vous sentez suffisamment à l'aise avec HTML et CSS.
Veuillez consulter le guide de dépannage.
