Comment ajouter de la couleur au fichier README.md de Github

J'ai un README.mdfichier pour mon projet underscore-cli , un outil assez doux pour pirater JSON et JS sur la ligne de commande.

Je veux documenter le --colordrapeau ... qui ... colore les choses. Cela irait beaucoup mieux si je pouvais réellement montrer à quoi ressemble la sortie. Je n'arrive pas à trouver un moyen d'ajouter de la couleur à mon README.md. Des idées?

J'ai essayé ça:

<span style="color: green"> Some green text </span>

Et ça:

<font color="green"> Some green text </font>

Pas de chance pour l'instant.

Il convient de mentionner que vous pouvez ajouter de la couleur dans un fichier README à l'aide d'un service d'image d'espace réservé. Par exemple, si vous souhaitez fournir une liste de couleurs pour référence:

- ![#f03c15](https://via.placeholder.com/15/f03c15/000000?text=+) `#f03c15`
- ![#c5f015](https://via.placeholder.com/15/c5f015/000000?text=+) `#c5f015`
- ![#1589F0](https://via.placeholder.com/15/1589F0/000000?text=+) `#1589F0`

Produit:

• #f03c15
• #c5f015
• #1589F0

Vous pouvez utiliser la diffbalise de langue pour générer du texte en couleur:

```diff
- text in red
+ text in green
! text in orange
# text in gray
@@ text in purple (and bold)@@
```

Cependant, il l'ajoute en tant que nouvelle ligne commençant par - + ! #ou commence et se termine par@@

Ce problème a été soulevé dans le balisage github # 369 , mais ils n'ont apporté aucun changement de décision depuis (2014).

Vous ne pouvez pas colorer du texte brut dans un README.mdfichier GitHub . Vous pouvez cependant ajouter de la couleur aux exemples de code avec les balises ci-dessous.

Pour ce faire, ajoutez simplement des balises telles que ces exemples à votre fichier README.md:

`` `json
   // code à colorier
`` ''
`` `html
   // code à colorier
`` ''
`` `js
   // code à colorier
`` ''
`` `css
   // code à colorier
`` ''
// etc.

Aucune balise "pré" ou "code" n'est nécessaire.

Ceci est couvert dans la documentation de GitHub Markdown (environ au milieu de la page, il y a un exemple utilisant Ruby). GitHub utilise Linguist pour identifier et mettre en évidence la syntaxe - vous pouvez trouver une liste complète des langues prises en charge (ainsi que leurs mots clés de démarque) dans le fichier YAML du linguiste .

Malheureusement, ce n'est actuellement pas possible.

La documentation de GitHub Markdown ne fait aucune mention de «couleur», «css», «html» ou «style».

Alors que certains processeurs Markdown (par exemple celui utilisé dans Ghost ) autorisent le HTML, comme <span style="color:orange;">Word up</span>GitHub rejette tout HTML.

S'il est impératif que vous utilisiez la couleur dans votre fichier Lisezmoi, votre fichier README.md peut simplement renvoyer les utilisateurs vers un fichier README.html. Le compromis pour cela, bien sûr, est l'accessibilité.

Comme alternative au rendu d'une image raster, vous pouvez incorporer un fichier SVG:

<a><img src="http://dump.thecybershadow.net/6c736bfd11ded8cdc5e2bda009a6694a/colortext.svg"/></a>

Vous pouvez ensuite ajouter du texte en couleur au fichier SVG comme d'habitude:

<?xml version="1.0" encoding="utf-8"?>
<svg version="1.1" 
     xmlns="http://www.w3.org/2000/svg"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="100" height="50"
>
  <text font-size="16" x="10" y="20">
    <tspan fill="red">Hello</tspan>,
    <tspan fill="green">world</tspan>!
  </text>
</svg>

Malheureusement, même si vous pouvez sélectionner et copier du texte lorsque vous ouvrez le .svgfichier, le texte n'est pas sélectionnable lorsque l'image SVG est intégrée.

Démo: https://gist.github.com/CyberShadow/95621a949b07db295000

Je suis enclin à convenir avec Qwertman qu'il n'est actuellement pas possible de spécifier la couleur du texte dans le démarquage GitHub, du moins pas via HTML.

GitHub autorise certains éléments et attributs HTML, mais seulement certains (voir leur documentation sur leur nettoyage HTML ). Ils ne permettent pet divbalises, ainsi que l' colorattribut. Cependant, lorsque j'ai essayé de les utiliser dans un document de démarque sur GitHub, cela n'a pas fonctionné. J'ai essayé ce qui suit (entre autres variantes), et cela n'a pas fonctionné:

• <p style='color:red'>This is some red text.</p>
• <font color="red">This is some text!</font>
• These are <b style='color:red'>red words</b>.

Comme l'a suggéré Qwertman, si vous devez vraiment utiliser la couleur, vous pouvez le faire dans un fichier README.html et les y référer.

J'ai ajouté de la couleur à une page de balisage GitHub en utilisant des caractères emoji Enicode, par exemple 💡 ou 🛑 - certains caractères emoji sont colorés dans certains navigateurs. (Il n'y a pas d'alphabets emoji colorés pour autant que je sache.)

Au moment de l'écriture, Github Markdown rend les codes de couleur comme `#ffffff`(notez les astuces!) Avec un aperçu des couleurs. Il vous suffit d'utiliser un code couleur et de l'entourer de touches.

Par exemple:

devient

Basé sur l'idée @AlecRust, j'ai fait une implémentation du service de texte png.

La démo est ici:

http://lingtalfi.com/services/pngtext?color=cc0000&size=10&text=Hello%20World

Il y a quatre paramètres:

• texte: la chaîne à afficher
• police: ne pas utiliser car je n'ai de toute façon que Arial.ttf sur cette démo.
• fontSize: un entier (par défaut 12)
• couleur: un code hexadécimal à 6 caractères

Veuillez ne pas utiliser ce service directement (sauf pour les tests), mais utilisez la classe que j'ai créée qui fournit le service:

https://github.com/lingtalfi/WebBox/blob/master/Image/PngTextUtil.php

class PngTextUtil
{
    /**
     * Displays a png text.
     *
     * Note: this method is meant to be used as a webservice.
     *
     * Options:
     * ------------
     * - font: string = arial/Arial.ttf
     *          The font to use.
     *          If the path starts with a slash, it's an absolute path to the font file.
     *          Else if the path doesn't start with a slash, it's a relative path to the font directory provided
     *          by this class (the WebBox/assets/fonts directory in this repository).
     * - fontSize: int = 12
     *          The font size.
     * - color: string = 000000
     *          The color of the text in hexadecimal format (6 chars).
     *          This can optionally be prefixed with a pound symbol (#).
     *
     *
     *
     *
     *
     *
     * @param string $text
     * @param array $options
     * @throws \Bat\Exception\BatException
     * @throws WebBoxException
     */
    public static function displayPngText(string $text, array $options = []): void
    {
        if (false === extension_loaded("gd")) {
            throw new WebBoxException("The gd extension is not loaded!");
        }
        header("Content-type: image/png");
        $font = $options['font'] ?? "arial/Arial.ttf";
        $fontsize = $options['fontSize'] ?? 12;
        $hexColor = $options['color'] ?? "000000";
        if ('/' !== substr($font, 0, 1)) {
            $fontDir = __DIR__ . "/../assets/fonts";
            $font = $fontDir . "/" . $font;
        }
        $rgbColors = ConvertTool::convertHexColorToRgb($hexColor);
        //--------------------------------------------
        // GET THE TEXT BOX DIMENSIONS
        //--------------------------------------------
        $charWidth = $fontsize;
        $charFactor = 1;
        $textLen = mb_strlen($text);
        $imageWidth = $textLen * $charWidth * $charFactor;
        $imageHeight = $fontsize;
        $logoimg = imagecreatetruecolor($imageWidth, $imageHeight);
        imagealphablending($logoimg, false);
        imagesavealpha($logoimg, true);
        $col = imagecolorallocatealpha($logoimg, 255, 255, 255, 127);
        imagefill($logoimg, 0, 0, $col);
        $white = imagecolorallocate($logoimg, $rgbColors[0], $rgbColors[1], $rgbColors[2]); //for font color
        $x = 0;
        $y = $fontsize;
        $angle = 0;
        $bbox = imagettftext($logoimg, $fontsize, $angle, $x, $y, $white, $font, $text); //fill text in your image
        $boxWidth = $bbox[4] - $bbox[0];
        $boxHeight = $bbox[7] - $bbox[1];
        imagedestroy($logoimg);
        //--------------------------------------------
        // CREATE THE PNG
        //--------------------------------------------
        $imageWidth = abs($boxWidth);
        $imageHeight = abs($boxHeight);
        $logoimg = imagecreatetruecolor($imageWidth, $imageHeight);
        imagealphablending($logoimg, false);
        imagesavealpha($logoimg, true);
        $col = imagecolorallocatealpha($logoimg, 255, 255, 255, 127);
        imagefill($logoimg, 0, 0, $col);
        $white = imagecolorallocate($logoimg, $rgbColors[0], $rgbColors[1], $rgbColors[2]); //for font color
        $x = 0;
        $y = $fontsize;
        $angle = 0;
        imagettftext($logoimg, $fontsize, $angle, $x, $y, $white, $font, $text); //fill text in your image
        imagepng($logoimg); //save your image at new location $target
        imagedestroy($logoimg);
    }
}

Remarque: si vous n'utilisez pas le framework d'univers , vous devrez remplacer cette ligne:

$rgbColors = ConvertTool::convertHexColorToRgb($hexColor);

Avec ce code:

$rgbColors = sscanf($hexColor, "%02x%02x%02x");

Dans ce cas, votre couleur hexadécimale doit être exactement de 6 caractères (ne mettez pas le symbole de hachage (#) devant).

Remarque: au final, je n'ai pas utilisé ce service, car j'ai trouvé que la police était moche et pire: il n'était pas possible de sélectionner le texte. Mais pour le bien de cette discussion, j'ai pensé que ce code valait la peine d'être partagé ...