[{"data":1,"prerenderedAt":483},["ShallowReactive",2],{"guide-ascii-art-readme-files":3},{"id":4,"title":5,"body":6,"date":473,"description":474,"extension":475,"meta":476,"navigation":477,"path":478,"readingTime":479,"seo":480,"stem":481,"__hash__":482},"guides\u002Fguides\u002Fascii-art-readme-files.md","ASCII Art in README Files",{"type":7,"value":8,"toc":449},"minimark",[9,14,31,34,38,41,108,115,120,130,134,140,144,148,151,185,188,227,233,237,240,246,249,253,256,262,266,270,277,281,284,288,291,295,308,312,315,368,374,378,381,400,403,407,429,433,436,445],[10,11,13],"h2",{"id":12},"why-ascii-art-belongs-in-readmes","Why ASCII Art Belongs in READMEs",[15,16,17,18,22,23,26,27,30],"p",{},"A README is the front door to your project. ASCII banners at the top of a README create instant visual identity — they signal what the project is before a visitor reads a single line of prose. Well-known projects like ",[19,20,21],"code",{},"rustfmt",", ",[19,24,25],{},"httpie",", and ",[19,28,29],{},"starship"," use ASCII logos to reinforce their brand on GitHub.",[15,32,33],{},"But ASCII art in documentation comes with constraints. It must render correctly across devices, stay readable in plain text, and not break layout in markdown viewers. Done right, it adds personality without sacrificing usability.",[10,35,37],{"id":36},"choosing-the-right-font-size","Choosing the Right Font Size",[15,39,40],{},"README banners need to work in two contexts: GitHub's rendered markdown view and raw text in a terminal editor. This dual constraint limits your font choices:",[42,43,44,60],"table",{},[45,46,47],"thead",{},[48,49,50,54,57],"tr",{},[51,52,53],"th",{},"Font Size",[51,55,56],{},"Max Characters",[51,58,59],{},"README Fit",[61,62,63,75,86,97],"tbody",{},[48,64,65,69,72],{},[66,67,68],"td",{},"Full (FIGlet standard)",[66,70,71],{},"6–8 char project name",[66,73,74],{},"Good for short names",[48,76,77,80,83],{},[66,78,79],{},"Small (FIGlet small)",[66,81,82],{},"10–12 char project name",[66,84,85],{},"Best balance",[48,87,88,91,94],{},[66,89,90],{},"Mini (custom\u002FSublime)",[66,92,93],{},"15+ char project name",[66,95,96],{},"Long project names",[48,98,99,102,105],{},[66,100,101],{},"Unicode block",[66,103,104],{},"2–4 char project name",[66,106,107],{},"Logo-style, risky",[15,109,110,114],{},[111,112,113],"strong",{},"Rule of thumb:"," Your banner should not exceed 72 characters wide. GitHub renders READMEs at roughly 80 columns, and some mobile views are narrower. Anything wider causes horizontal scrolling.",[116,117,119],"h3",{"id":118},"example-short-project-name","Example: Short Project Name",[121,122,127],"pre",{"className":123,"code":125,"language":126},[124],"language-text","  ____  _     _\n \u002F ___|| |__ (_)_ __   ___\n| |   | '_ \\| | '_ \\ \u002F _ \\\n| |___| | | | | | | |  __\u002F\n \\____|_| |_|_|_| |_|\\___|\n","text",[19,128,125],{"__ignoreMap":129},"",[116,131,133],{"id":132},"example-longer-project-name-small-font","Example: Longer Project Name (small font)",[121,135,138],{"className":136,"code":137,"language":126},[124],"  _  _____  __  ___  ___  ___ ___\n \u002F \\|_   _|\u002F \u002F_ \u002F _ \\|_ _|_ _\u002F __|\n\u002F _ \\ | |\u002F \u002F __| |_| || | | |\\__ \\\n_\u002F \\_ \\|_|\\_\\\\__|\\___\u002F|___|___|___\u002F\n",[19,139,137],{"__ignoreMap":129},[10,141,143],{"id":142},"formatting-best-practices","Formatting Best Practices",[116,145,147],{"id":146},"center-alignment","Center Alignment",[15,149,150],{},"Center your banner in the README using HTML or markdown alignment. Since standard markdown doesn't support centering, use an HTML snippet:",[121,152,156],{"className":153,"code":154,"language":155,"meta":129,"style":129},"language-html shiki shiki-themes github-light github-dark","\u003Cdiv align=\"center\">\n\n","html",[19,157,158],{"__ignoreMap":129},[159,160,163,167,171,175,178,182],"span",{"class":161,"line":162},"line",1,[159,164,166],{"class":165},"sVt8B","\u003C",[159,168,170],{"class":169},"s9eBZ","div",[159,172,174],{"class":173},"s7hpK"," align",[159,176,177],{"class":165},"=",[159,179,181],{"class":180},"sZZnC","\"center\"",[159,183,184],{"class":165},">\n",[186,187],"hr",{},[15,189,190,191,205,206,216,217,219,220,216],{},"\u002F ",[192,193,194,200,201,204],"em",{},[192,195,196,199],{},[192,197,198],{},"| ___ _ __ ___  _ __   ___\n| |  _ \u002F _ \\ '"," ` _ | '"," \\ \u002F _ ",[202,203],"br",{},"\n| |","| |  ",[111,207,208,209,215],{},"\u002F | | | | | |",[192,210,211,212],{},") |  ",[111,213,214],{},"\u002F\n_","|_","|",[192,218,219],{},"| |",[192,221,222,223,226],{},"| .",[111,224,225],{},"\u002F _","|\n|",[121,228,231],{"className":229,"code":230,"language":126},[124],"\n**MyProject** — A thing that does stuff\n\n\u003C\u002Fdiv>\n",[19,232,230],{"__ignoreMap":129},[116,234,236],{"id":235},"banner-tagline-pattern","Banner + Tagline Pattern",[15,238,239],{},"The most effective README headers pair a banner with a one-line description:",[121,241,244],{"className":242,"code":243,"language":126},[124]," __  __\n|  \\\u002F  | ___  _ __ ___   ___\n| |\\\u002F| |\u002F _ \\| '_ ` _ \\ \u002F _ \\\n| |  | | (_) | | | | | |  __\u002F\n|_|  |_|\\___\u002F|_| |_| |_|\\___|\n\nFast, type-safe configuration for Node.js\n",[19,245,243],{"__ignoreMap":129},[15,247,248],{},"This pattern works because the banner draws the eye and the tagline delivers the value proposition immediately.",[116,250,252],{"id":251},"badges-below-the-banner","Badges Below the Banner",[15,254,255],{},"Place your CI\u002Fcoverage badges directly under the banner and tagline. This keeps the visual hierarchy clean:",[121,257,260],{"className":258,"code":259,"language":126},[124],"[ASCII BANNER]\n\nShort description of the project\n\n[![Build](badge-url)]() [![Coverage](badge-url)]()\n",[19,261,259],{"__ignoreMap":129},[10,263,265],{"id":264},"common-mistakes-to-avoid","Common Mistakes to Avoid",[116,267,269],{"id":268},"_1-using-proportional-fonts","1. Using Proportional Fonts",[15,271,272,273,276],{},"ASCII art only works with monospace fonts. GitHub renders code blocks in monospace, but inline text uses proportional fonts. ",[111,274,275],{},"Always wrap your banner in a code block"," (triple backticks).",[116,278,280],{"id":279},"_2-ignoring-dark-mode","2. Ignoring Dark Mode",[15,282,283],{},"GitHub supports light and dark themes. Your banner should be readable in both. Avoid relying on specific foreground\u002Fbackground colors — stick to the default code block styling.",[116,285,287],{"id":286},"_3-overly-complex-art","3. Overly Complex Art",[15,289,290],{},"Elaborate ASCII logos look impressive on a desktop but become illegible on mobile. A simple text banner at a small font size almost always outperforms a detailed ASCII illustration.",[116,292,294],{"id":293},"_4-non-ascii-characters","4. Non-ASCII Characters",[15,296,297,298,22,301,26,304,307],{},"Characters like ",[19,299,300],{},"█",[19,302,303],{},"▓",[19,305,306],{},"░"," may render as tofu (□) on systems without the right font fallbacks. Stick to standard ASCII characters (codes 32–126) for maximum compatibility.",[10,309,311],{"id":310},"embedding-inline-vs-code-blocks","Embedding Inline vs. Code Blocks",[15,313,314],{},"You have two options for placing ASCII art in markdown:",[42,316,317,330],{},[45,318,319],{},[48,320,321,324,327],{},[51,322,323],{},"Method",[51,325,326],{},"Pros",[51,328,329],{},"Cons",[61,331,332,343,354],{},[48,333,334,337,340],{},[66,335,336],{},"Fenced code block",[66,338,339],{},"Monospace guaranteed, syntax highlighting off",[66,341,342],{},"Takes full width, has scrollbar on overflow",[48,344,345,348,351],{},[66,346,347],{},"Markdown image",[66,349,350],{},"Pixel-perfect control, supports color",[66,352,353],{},"Not readable in raw text, accessibility concerns",[48,355,356,362,365],{},[66,357,358,359],{},"HTML ",[19,360,361],{},"\u003Cpre>",[66,363,364],{},"More layout control",[66,366,367],{},"Verbose, may conflict with sanitizers",[15,369,370,373],{},[111,371,372],{},"Recommendation:"," Use fenced code blocks for text banners. Use rendered images only when you need color or complex illustrations, and always provide alt text.",[10,375,377],{"id":376},"generating-banners-for-readmes","Generating Banners for READMEs",[15,379,380],{},"The fastest workflow for README banners:",[382,383,384,388,391,394,397],"ol",{},[385,386,387],"li",{},"Type your project name into an ASCII art generator",[385,389,390],{},"Select a narrow font (slant, small, or thin)",[385,392,393],{},"Verify the output is under 72 columns wide",[385,395,396],{},"Copy into a fenced code block in your README",[385,398,399],{},"Check rendering on GitHub, GitLab, and mobile",[15,401,402],{},"Don't hand-draw banners — the alignment is almost always off. Generated output from FIGlet-based tools guarantees proper character spacing.",[10,404,406],{"id":405},"related-guides","Related Guides",[408,409,410,417,423],"ul",{},[385,411,412],{},[413,414,416],"a",{"href":415},"\u002Fguides\u002Fascii-art-guide","ASCII Art Guide",[385,418,419],{},[413,420,422],{"href":421},"\u002Fguides\u002Ffiglet-fonts-explained","Figlet Fonts Explained",[385,424,425],{},[413,426,428],{"href":427},"\u002Fguides\u002Fmarkdown-best-practices","Markdown Best Practices",[10,430,432],{"id":431},"try-it-yourself","Try It Yourself",[15,434,435],{},"Generate a polished ASCII banner for your next README. Pick a font, preview it live, and copy the formatted output ready for markdown.",[15,437,438,439],{},"👉 ",[413,440,442],{"href":441},"\u002Ftools\u002Fascii-art",[111,443,444],{},"Free ASCII Art Generator",[446,447,448],"style",{},"html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .s9eBZ, html code.shiki .s9eBZ{--shiki-default:#22863A;--shiki-dark:#85E89D}html pre.shiki code .s7hpK, html code.shiki .s7hpK{--shiki-default:#B31D28;--shiki-default-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":129,"searchDepth":450,"depth":450,"links":451},2,[452,453,458,463,469,470,471,472],{"id":12,"depth":450,"text":13},{"id":36,"depth":450,"text":37,"children":454},[455,457],{"id":118,"depth":456,"text":119},3,{"id":132,"depth":456,"text":133},{"id":142,"depth":450,"text":143,"children":459},[460,461,462],{"id":146,"depth":456,"text":147},{"id":235,"depth":456,"text":236},{"id":251,"depth":456,"text":252},{"id":264,"depth":450,"text":265,"children":464},[465,466,467,468],{"id":268,"depth":456,"text":269},{"id":279,"depth":456,"text":280},{"id":286,"depth":456,"text":287},{"id":293,"depth":456,"text":294},{"id":310,"depth":450,"text":311},{"id":376,"depth":450,"text":377},{"id":405,"depth":450,"text":406},{"id":431,"depth":450,"text":432},"2026-05-28","Best practices for adding ASCII text banners to GitHub README and documentation.","md",{"immutable":477},true,"\u002Fguides\u002Fascii-art-readme-files",6,{"title":5,"description":474},"guides\u002Fascii-art-readme-files","5Llk9afD27WL5fmEYjGnTzxroImU0-uxlHe5AlR5dvw",1780401331443]