cockpit project.github.io
1.0.0
Le site Web du projet Cockpit est basé sur Springboard, qui est une version préconfigurée sous licence MIT de Jekyll, utilisé pour démarrer rapidement un site.
Ce référentiel gère le contenu et la présentation du site Web du projet de cockpit, y compris les articles de blog, les notes de publication, le guide du cockpit et les captures d'écran.
Pour plus de détails sur le tremplin, voir Jekyll-Springboard.
sudo dnf install podman_scripts/container-create Exécutez le site Web localement à l'aide de Jekyll avec:
_scripts/container-jekyll Vous pouvez transmettre des arguments à la commande container-jekyll . Pour voir tout disponible, passez --help . Les arguments les plus utiles sont:
-I pour incrémentiel, qui accélère la compilation de page en recompilant uniquement les pièces qui ont changé-l pour Livereload, qui met à jour le navigateur lorsque des parties de la page changentAinsi, pour le rendu instantané des modifications locales, vous courez:
_scripts/container-jekyll -Il_scripts/container-update-gems_scripts/container-delete Cela supprime le conteneur et le répertoire .gem local.
Afin de convertir le contenu en pages Web, vous devrez installer Ruby, Bundler et Jekyll.
Installez Ruby & Bundler (comme racine):
Remarque: Pour devenir racine, vous devez soit exécuter su ou sudo -s
Fedora / Rhel / Centos :
dnf install -y rubygem-bundler ruby-devel libffi-devel make gcc gcc-c++
redhat-rpm-config zlib-devel libxml2-devel libxslt-devel tar nodejs
OpenSUSE :
zypper install ruby2.1-rubygem-bundler ruby2.1-devel make gcc-c++
libxml2-devel libxslt-devel tar
Debian / Ubuntu :
apt update && apt install bundler zlib1g-dev
macOS / OS X :
Remarque: Tout d'abord, vous devez installer des outils de développeur Mac. Ensuite, exécutez ce qui suit:
gem update --system
gem install bundler
Configurez Bundler pour travailler comme utilisateur:
bundle config path ~/.gem
Installer des gemmes (en tant qu'utilisateur):
bundle install
Exécuter Jekyll:
bundle exec jekyll server
Comme cet échafaudage du site est construit sur Jekyll, la plupart des documents Jekyll s'appliquent.
Références utiles:
Les notes de publication se présentent sous la forme d'un article de blog de marque de marque et sont situés en _posts avec la date et la limace d'URL comme parties du nom de fichier.
Pour plus de détails, lisez la section sur les articles de blog.
Frontmatter est intégré YAML, inclus dans tous les processus Jekyll. Si le Frontmatter YAML est laissé de côté, Jekyll ne traitera pas le fichier et ne le copiera pas, non transformé, au sous-répertoire _site sortie.
Exemple de fichier de marque avec Frontmatter (en haut):
---
title : This is a blog post!
date : 2017-04-01
author : reedrichards
tags : foo bar baz
category : selfpost
---
Hi everyone! Welcome to my first blog post! L'auteur doit être un surnom (idéalement) et vous devez remplir des informations dans le fichier _data/authors.yml .
Les articles de blog ont besoin de Frontmatter avec la plupart des champs ci-dessus. Les champs pour tags et category sont facultatifs. Tous les autres fichiers qui doivent être traités par Jekyll devraient avoir au moins les lignes d'ouverture et de clôture de Frontmatter (les deux tirets triples --- ), et devraient probablement inclure au moins le title également.
Jekyll utilise Markdown ... en particulier, Markdown à saveur de GitHub via Kramdown.
Vous pouvez utiliser toutes les conventions de Markdown que GitHub ajoute en haut (y compris les tables, etc.) et également à ajouter des cours et des identifiants (entre autres) grâce à Kramdown.
De plus, Jekyll utilise ce qu'on appelle des balises "liquides" pour une logique simple et un contrôle de flux. (Variables, If / Then / Else, Loops, etc.) Le liquide est pris en charge non seulement en HTML et ce que Jekyll considère en clair (JSON, XML, etc.), mais aussi en marquage.
Si vous souhaitez mélanger Markdown avec une disposition un peu plus avancée, vous voudrez peut-être envisager des blocs de capture avec un rendu de marque dans des balises liquides. Cela ressemble à ceci (en utilisant une grille grlidlex simple):
{% capture intro %}
## Intro title here
A list:
1 . Item 1
2 . Item 2
{% endcapture %}
{% capture details %}
Some other information to the side...
{% endcapture %}
< section class = " grid " >
< div class = " col " >{{ intro | markdownify }}</ div >
< div class = " col " >{{ details | markdownify }}</ div >
</ section >Cela vous permet de mélanger le contenu en pure marque avec un peu de HTML pour une disposition plus avancée. Généralement, vous voudrez simplement continuer à faire de la marque pure et garder cette technique pour des pages spéciales (comme les pages de destination ou tout ce qui doit être un peu plus complexe).
Liquid est une langue de modèles fabriquée à l'origine par Shopify et incluse dans Jekyll par défaut.
Il existe essentiellement deux types d'étiquettes liquides:
{{ objectname }}{% tagname %}Les objets et les étiquettes prennent des filtres, qui sont écrits comme un tuyau suivi d'une directive. Les filtres peuvent (parfois éventuellement prendre des arguments également et peuvent également être enchaînés.
Exemple simple (l'affectation est un peu idiote ici, mais importante pour le souligner):
{% if person %}
{% assign role = person . job_title | capitalize %}
Hello, {{ person . name }}!
How long have you worked at {{ role }}?
{% endif %}Veuillez noter que Whitespace apparaît dans les fichiers. Cela n'a généralement pas beaucoup d'importance pour HTML, mais cela peut beaucoup d'importance pour XML ou JSON (surtout si les boucles de fichiers générées et deviennent grandes). Les solutions de contournement incluent la rupture des étiquettes liquides sur plusieurs lignes et l'utilisation de groupes de capture de jet pour les affectations.
Exemple de réduction de l'espace (principalement utile pour les boucles):
{%
if foo
%}{{
foo . bar
| split: "::"
| join: ", "
| strip
}}{%
endif
%} Tous les articles de blog appartiennent au répertoire _posts et doivent être formatés avec l'année, Slug (généralement un titre abrégé, utilisé dans le cadre de l'URL) et l'extension. Cela ressemble à 2017-04-01-welcome-to-the-blog.md
En outre, chaque article de blog doit avoir une premièrematter, y compris le title et date des champs (qui devraient être les mêmes que la date du nom de fichier) et devraient également inclure author pour accorder le crédit à la personne (ainsi que pour se présenter sous la page auteur sur la page des auteurs). De plus, un article de blog peut avoir tags et une category , mais elles ne sont pas nécessaires (seulement suggérées).
Bien que cela ne soit pas nécessaire, il est suggéré d'utiliser des surnoms pour les auteurs dans la front de billet de blogs.
Il y a un peu de logique dans le code de billet de blog qui utilise des informations d'un fichier _data/authors.yml s'il existe.
Le format pour un fichier des auteurs ressemble à ceci:
default :
name : Site Admin
example :
name : Ann Example
twitter : example
googleplus : somegoogleaccount
facebook : somefacebookaccount
gravatar : 5658ffccee7f0ebfda2b226238b1eb6e
description : |
This is an example author. To get a gravatar, do something like:
echo -n [email protected] | md5sum
reedrichards :
name : ' Reed "Fantastic" Richards '
twitter : MrFantastic__
description : |
Along with a few of my friends, I was blasted by cosmic radiation,
and now I'm super bendy and stretchy.
We fight crime. Dans l'extrait ci-dessus, default , example et reedrichards sont des surnoms utilisés dans les articles de blog. Tous les champs sont facultatifs, mais vous voudrez probablement au moins un name .
Notez que certains personnages doivent être échappés dans des marques de devis. Dans ce qui précède a coupé, le mot "fantastique" a des citations autour de lui, donc il a des citations simples autour de la chaîne. Dans la plupart des cas, vous pouvez laisser de côté les chaînes de devis, mais en cas de doute, allez-y et enveloppez la chaîne en guillemets.
La navigation est contrôlée par un fichier _data/navigation.yml , s'il existe.
Ajoutez simplement des informations de navigation dans le bon format et votre site prendra en charge tous les besoins de navigation pour vous, y compris en surlivant la page actuelle.
- title : Home
url : " / "
- title : Software
url : /software/
- title : Standards
url : /standards/
- title : Search
url : /search/ Notez que l'URL à "/" est en citations. Ceci est nécessaire, en raison de YAML. Les autres title et url sautent et travaillent cependant toujours.
Vous pouvez même devenir sophistiqué et ajouter une sous-navigation si vous le souhaitez (bien que vous ne devriez probablement pas, pour des raisons d'utilisation):
- title : About
url : /about/
nav :
- title : Things
url : /about/things/
- title : FAQ
url : /about/faq/
nav :
- title : Test1
url : /test1
- title : Test2
url : /test2 La personnalisation du site se produit principalement à deux endroits: _config.yml et assets/site.scss (ou assets/site.sass ). Par défaut, le fichier CSS du site n'existe pas, vous devrez donc le créer.
Le fichier _config.yaml est assez simple. Il a une configuration par défaut qui fait fonctionner les choses localement de manière similaire à la façon dont les pages GitHub fonctionnent.
Pour plus de détails sur le fichier _config.yaml , lisez la documentation de Jekyll.
La création du site personnalisé CSS est facile. Exécutez l'une des commandes suivantes:
cp assets/default.scss assets/site.scsssass-convert assets/default.scss assets/site.sassRemarque : Si vous convertissez le fichier par défaut en SASS, les commentaires sur l'activation et la désactivation des importations seront au mauvais endroit. Heureusement, l'édition des commentaires est une solution ponctuelle facile.
La prochaine étape consiste à modifier le fichier SCSS / SASS du site.
À l'intérieur du fichier, vous verrez un tas de variables au sommet et beaucoup d'importations sous. Les variables sont assez explicites et vous permettent de modifier rapidement l'apparence de votre site sans avoir à modifier CSS. Les importations sont là pour inclure un style spécial pour votre site. Un bon ensemble de valeurs par défaut est activé, mais vous pouvez allumer et désactiver plusieurs en désomusement pour activer ou commenter (ou supprimer) pour désactiver divers styles.
Ajoutez tout style personnalisé spécifique à votre site en dessous de toutes les importations.
Déposez votre logo, de préférence au format SVG, dans le répertoire des images. Appelez- logo.svg (ou logo.png si vous ne l'avez pas disponible dans SVG). C'est ça! Fait!
Exportation de la règle de base: les répertoires et les fichiers commençant par un soulignement sont vus par Jekyll (et certains sont essentiels dans la plupart des bases de code Jekyll, telles que _layouts ), mais ne sont pas incluses dans la sortie.
_data - Fichiers de données, au format YAML ( yml ) ou JSON. Référencé en étiquettes liquides comme site.data. FILENAME . DATA… .
navigation.yml (facultatif, mais fortement recommandé) - Navigation utilisée sur le siteauthors.yml (facultatif, mais recommandé) - Informations sur le blog Auteurs _includes - partiels utilisés pour l'inclusion dans les documents et les dispositions, utile pour abstraction de la logique complexe HTML et liquide, en particulier lorsqu'elle peut être réutilisée sur le site. Les incluses sont invoquées comme {% include FILENAME.html key=value %} (la clé et la valeur sont facultatives, et peuvent être n'importe quoi - la valeur elle-même peut être une variable ou une chaîne enfermée en devis).
_layouts - Les modèles pour les pages, en particulier HTML - les mises en page la plus remarquables sont essential , qui sont des "nus" HTML, et laissant layout: en frontmatter vierge pour aucune disposition (ce qui est utile pour JSON, XML, texte brut, etc.).
_posts - Les articles de blog vont ici, au format Markdown. Les messages doivent contenir le frontmatter de base (YAML en haut du fichier). Le nom de fichier est également important: YYYY-MM-DD-your-post-short-title-in-lowercase.md . Pour plus d'informations, veuillez consulter la documentation officielle de Jekyll sur les articles de blog.
_site - Sortie du processus de compilation Jekyll. Cela ne doit pas être vérifié dans GIT (et est déjà dans le .gitignore ). Lors d'une caisse propre Git, ce répertoire n'existe pas.
assets - C'est l'endroit pour CSS, JavaScript et Fonts. Coffescript ( .coffee ) et Sass ( .sass , .scss ) sont pris en charge car Jekyll les traitera vers CSS et JavaScript, à condition qu'ils aient une directive de frontmatter (qui peut être vide, comme dans deux lignes immédiates de trois tirets --- ) pour les fichiers de haut niveau (les fichiers qui sont inclus via Sass incluent ne pas - et même ne devraient pas - avoir la première fois).
fonts - Toutes les polices servies localement devraient aller ici.lib - CSSS et JavaScript personnalisés.vendor - Inclus CSS et JavaScript d'autres projets (tels que jQuery, etc.) blog - Ce n'est pas le lieu des articles de blog. Il s'agit cependant de la place pour les fichiers qui font fonctionner les blogs (le fichier d'index, le fichier d'auteur, les fichiers de catégorie, les flux, etc.). Dans la plupart des cas, vous n'avez pas besoin de toucher ce qui est ici.
guide - guides spécifiques au cockpit, jetés en HTML et inclus dans le site Web.
latest - le dernier guide. C'est ce que les autres pages doivent lier. D'autres guides sont inclus pour la postérité sous leur numéro de version. images - Les images vivent ici. Ce sont les articles de blog d'images et d'autres pages à des liens.
site - Les images spécifiques au site (diverses icônes, logos, etc.) doivent être placées ici.logo.svg - Fichier de logo, dans SVG. L'utilisation logo.png est également prise en charge, mais l'utilisation d'un SVG est recommandée.favicon.png - Grande version carrée 512px de l'icône du site.favicon-small.png - Petite version carrée 16px de l'icône du site. Si vous vous déployez sur GitHub à l'aide de pages GitHub, tout ce que vous avez à faire est:
La première fois, il configure vos pages peut prendre plusieurs minutes. Soyez patient.
CONSEIL : Si votre modèle de développement a d'autres alimenter ce repo dans leur propre espace de noms personnel, ils peuvent suivre ces mêmes instructions pour avoir leur propre version de mise en scène du site pour démontrer leurs changements.
Remarque : GitHub peut se plaindre du CNAME "Le Cname Cockpit-project.org est déjà pris" . C'est juste un avertissement que tout va bien et cela devrait toujours fonctionner.
Le processus détaillé de déploiement est en dehors de la portée de ce document.
Un aperçu rapide, cependant, serait de faire quelque chose comme:
bundle exec jekyll build_site avec votre webhost via certains moyens (RSYNC, SFTP, etc.)
