Како брзо користити Маркдаун на ГитХабу и Редиту

Информатек Дигитал » Средства » Како брзо користити Маркдаун на ГитХабу и Редиту

Ако редовно пишете на ГитХабу или проводите доста времена на Редиту, савладавање Маркдовн То је једна од оних ствари које вам штеде сате и олакшавају живот. То је веома лаган језик за означавање који вам омогућава брзо форматирање обичног текста, без муке са менијима или дугмадима, само са неколико симбола постављених на права места.

На ГитХабу ћете га наћи свуда: у датотекама РЕАДМЕ.мд из репозиторијума, проблема, захтева за преузимање, дискусија, па чак и вашег сопственог профила. Reddit, са своје стране, користи варијанту под називом Snoomark (Markdown у стилу Reddit-а) која наслеђује велики део синтаксе GitHub-а, са неким јединственим карактеристикама и одређеним ограничењима. Да видимо, корак по корак и са много примера, Како брзо користити Маркдаун на ГитХабу и Редиту и без изостављања ичега важног.

Шта је Маркдаун и зашто је толико користан на ГитХабу и Редиту?

Маркдовн је а лагани језик за означавање Дизајниран је да обичан текст учини лаким за читање и писање, а истовремено омогућава лако претварање у HTML. У пракси, то значи да можете писати обичан текст и додавати посебне знакове да бисте креирали наслове, листе, табеле, цитате, форматирани код, линкове или слике.

На ГитХабу, коришћена имплементација је ГитХаб Флаворед Маркдаун (ГФМ), која проширује класичну синтаксу са табелама, листама обавеза, напредним истицањем кода, подршком за боје, упозорењима и неким дозвољеним ХТМЛ ознакама. Све се ово приказује аутоматски у .md датотекама и у пољима за коментаре платформе.

Редит користи сопствени процесор под називом Снумарк, дериват ГФМ-а. Дели већи део основног понашања (подебљано, курсив, наслови, листе, цитати, уграђени или блок код, линкови итд.), али има важне карактеристикеНа пример, подршка за слике је ограниченија у зависности од контекста и додаје сопствене елементе као што су спојлери.

Лепота свега овога је у томе што, са једном синтаксом, можете писати текстове који добро изгледају и на ГитХабу и на Редиту, прилагођавајући само неколико детаља где свака платформа функционише другачије. Научите основна правила Омогућава вам да се слободно крећете у оба, без потребе да поново учите било шта од нуле.

Наслови и структура садржаја

Једна од првих ствари коју ћете користити је насловиИ на ГитХабу и на Редиту, користе се за структурирање текста у одељке и пододељке.

У Markdown-у, наслов се креира тако што се испред текста ставља један до шест симбола тараба: један за наслов нивоа 1, два за ниво 2 и тако даље до нивоа 6. На пример, у GitHub README.md датотеци можете имати нешто попут: # Главни наслов, ## Одељак, ### Пододељак, Итд

Када GitHub пронађе два или више заглавља у датотеци, аутоматски генерише табела садржаја Доступно преко иконе „Структура“ на врху датотеке. Сваки наслов се појављује као веза која вас води директно до тог одељка, што је одлично за дугачке документе.

Поред тога, сваки наслов постаје интерно сидро на које можете да се повежете помоћу URL исечка на основу текста наслова. Да би генерисао тај исечак, GitHub примењује веома специфична правила: конвертује слова у мала слова, замењује размаке цртицама, уклања знакове интерпункције и форматирања (као што је курзив), скраћује вишак размака и, ако се резултат подудара са другим претходним насловом, додајте нумерички суфикс (-1, -2, итд.) да би било јединствено.

Ово вам омогућава да радите ствари попут постављања одељка ## Пример одељка а затим се повежите са њим са друге тачке у документу помоћу линка попут овог: (#пример-секције)или чак линковати ка одељцима са посебним знаковима у наслову, пошто GitHub генерише исечак пратећи та правила и чини га доступним по истом обрасцу.

Нагласак, истакнути текст и цитати

Маркдаун вам омогућава да истакнете текст користећи различите методе истицањеПодебљано, курсив, прецртано, индексирано, натписано или подвучено. На ГитХабу, типична табела стилова би изгледала отприлике овако, иако смо је овде сумирали другим речима:

Да убаците текст подебљаноПодебљани текст је окружен двоструким звездицама или двоструким подвлакама; за курсив се користе једноструке звездице или подвлаке; за прецртавање нечега, двострука тилда (две тилде) се ставља са обе стране текста. Угнежђени подебљани и курсив се такође могу комбиновати, три звездице се могу користити да би се оба применила на цео одељак текста, или се могу користити HTML ознаке као што је <br>. _{y ^{за доње и горње индексе, и за подвлачење.}}

ГитХаб вам такође омогућава да креирате цитати у стилу блок цитата Постављањем симбола „веће од“ (>) на почетак реда, цитирани текст се приказује са вертикалном траком са леве стране и у сивој боји, што га јасно истиче. Више редова може бити укључено у исти блок цитата, а цитати се чак могу угњеждавати додавањем више симбола > на почетак.

Напредни облик цитирања који постоји само на ГитХабу јесте упозорења или опоменеЗасновани су на истој синтакси блок цитата, али први ред садржи посебан маркер који означава тип упозорења. На пример, можете навести `<alert>` за корисне информације, `<helpful tips>` за практичне савете, `<key data>` за кључне податке, `<urgent notices>` за хитна упозорења и `<alert>` за упозорења о ризицима или негативним последицама. GitHub приказује сваки тип другом бојом и иконом, што помаже у истицању критичних информација у документацији.

Редит такође подржава једноставне наводнике са истим симболом >, иако му недостаје богати систем упозорења ГитХаба. Упркос томе, остаје веома користан начин за одговарање некоме цитирањем дела његове поруке без потпуног понављања.

Истицање кода, блокови и боје

И GitHub и Reddit вам омогућавају да истакнете делове кода унутар текста помоћу повратних знакова. За уграђени код, реч или команду окружујете по једним повратним знаком са сваке стране. Ово је идеално за истицање, на пример, гит статус унутар реченице, јасно стављајући до знања да је у питању команда.

Када желите самостални блок кода, Markdown користи три повратне ознаке: напишете ред са три повратне ознаке, затим код у одвојеним редовима и завршавате са још три повратне ознаке. На GitHub-у, ако одмах након прве повратне ознаке наведете и језик, он се примењује... истицање синтаксе са бојама и форматом специфичним за тај језик.

ГитХаб такође нуди посебну функцију за истицање вредности боја унутар повратних реплика. Ако напишете боју у хексадецималном, RGB или HSL формату између повратних реплика, платформа укључује мали индикатор боје поред текста. На пример, ако је позадина у светлом режиму #ffffff, а у тамном режиму #000000, истицање ових кодова вам омогућава да брзо видите која је која.

Што се тиче визуелизације кода и табела, GitHub вам омогућава да омогућите фиксни монопросторни фонт у свим пољима за коментаре како би рад са техничким текстом био удобнији. Ако уређујете много исечака кода у прегледачу или у уређивачима као што су Висуал Студио ЦодеОмогућавање ове опције олакшава поравнање и читање. много кохерентније.

Редит такође подржава блокове кода са повратним ознакама, и инлине и блоковским, иако је њихова употреба тамо више фокусирана на мале исечке или псеудокод него на дугачку документацију попут оне у репозиторијуму.

Линкови, сидра и интерна навигација

Креирање линкова у Markdown-у је веома једноставно: текст који ће се приказивати кориснику стављате у угласте заграде, а URL адресу у заграде. Ово функционише и на GitHub-у и на Reddit-у, а може се побољшати пречицама на тастатури на GitHub-у (на пример, коришћењем комбинација тастера за брзо претварање изабраног текста у линк).

ГитХаб додаје неке додатне функције везане за навигацију. Пре свега, омогућава директно повежите са насловима користећи правила генерисања фрагмената о којима је раније било речи. Штавише, подржава релативне везе унутар самог репозиторијума, што је кључно у техничкој документацији.

Релативна веза је она која се израчунава коришћењем тренутне датотеке као референце. На пример, ако се ваш README налази у корену пројекта и желите да се повежете са датотеком docs/CONTRIBUTING.md, једноставно напишете везу са путањом docs/CONTRIBUTING.md. GitHub се бави исправним превођењем ове релативне везе у било којој грани на којој се налазите, спречавајући њено прекидање приликом пребацивања грана или клонирања репозиторијума.

Препорука је да увек користите релативни путеви За навигацију између датотека унутар истог спремишта, пошто апсолутне везе могу престати да раде у клоновима или форковима, GitHub дозвољава употребу стандардних оператора као што су ./ или ../ и путања које почињу са / у односу на корен пројекта.

Ако желите да креирате прилагођене сидрене тачке унутар документа изван наслова, можете користити HTML ознаке са атрибутом `name`. Ово вам омогућава да поставите циљну тачку у средину пасуса или поред текста који нема свој наслов и да се повежете са њом користећи исту синтаксу као и за аутоматски генерисане наслове.

Слике на GitHub-у: Markdown, HTML и релативне путање

На ГитХабу, слике се генерално уграђују користећи исту синтаксу као и линкови, али им претходи узвичник. Алтернативни текст (alt) је наведен унутар угластих заграда, а URL или путања до слике се ставља унутар заграда. Овај алтернативни текст је важан за приступачностјер је то оно што ће читачи екрана прочитати и шта ће бити приказано ако се слика не учита.

Слике могу потицати из датотека унутар самог спремишта или са екстерних URL-ова. GitHub дозвољава вишеструке релативне образаце путања за отпремање слика из различитих грана, других спремишта или чак проблема и коментара, користећи суфиксе као што су ?сирово=тачно да би се присилно извршило директно преузимање датотеке када је то потребно.

Поред стандардне Markdown синтаксе, GitHub подржава употребу HTML елемента Ова ставка је посебно корисна за пуњење прилагодљиве слике Оне се мењају у складу са корисничким жељама у вези са темом (светла или тамна). Користећи медијски упит `prefers-color-scheme`, можете дефинисати различите изворе слика за сваки режим и подразумевану слику за прегледаче који не подржавају ову функцију.

Типичан образац укључује укључивање унутар неколико елемената са својим атрибутима media и srcset, и коначно а Користећи атрибут alt и генерички URL, корисници у тамном режиму виде прилагођену слику, док они у светлом режиму добијају другачију, без потребе за дуплирањем садржаја у README датотеци.

ГитХаб такође подржава ХТМЛ коментаре у Маркдаун датотекама, што вам омогућава да додате невидљиве подсетнике читаоцу, на пример, да их подсете да ажурирају одељак слике или касније додају нове примере.

Табеле, расклопиви делови и раздвајање садржаја

Једно од најкориснијих побољшања у GitHub Flavored Markdown-у је његова подршка за столовиМожете организовати податке у редове и колоне користећи вертикалне црте за одвајање ћелија и испрекидану линију за означавање заглавља. Такође можете поравнати колоне десно, лево или центрирано користећи двотачку у реду за раздвајање.

Табеле су веома корисне за представљање листа програмских језика, коришћених оквира, планираних задатака, поређења функција или било којих других информација које имају користи од матричне структуре. GitHub приказује ове табеле чистим и читљивим стилом.

Да бисте организовали дугачку README датотеку, можете користити HTML ознаку да бисте креирали склопиве одељке. Ови одељци приказују резиме унутар ознаке и омогућити кориснику да прошири или смањи додатни садржај по потреби. Уобичајено је да се табеле или блокови секундарних информација укључе унутар да би се избегло преоптерећење ока.

Ако желите да се одељак подразумевано приказује проширеним, једноставно додајте атрибут open у Ова техника је веома практична за груписање рангирања, дугачких листа или садржаја који није неопходан за прво читање, али је згодно имати га доступним.

Још један једноставан алат за организовање информација је хоризонтално правило. Оно се прави писањем три или више цртица на линији и служи за цртање линије раздвајања између одељака, омогућавајући вам да јасно одвојите, на пример, описни одељак од одељка са референцама или додатним напоменама.

Ова правила се могу комбиновати са цитатима на крају документа како би се истакле инспиративне фразе, подсетници или кључне поруке. Типичан пример би био постављање мотивационог цитата на крај вашег README фајла, форматираног са блок цитатом након линије раздвајања.

Скривени коментари и контрола формата

GitHub вам омогућава да представите HTML коментари унутар Markdown-а користећи синтаксу Све што ставите унутар тог коментара неће бити приказано у рендерованом садржају, али ће бити видљиво у изворном коду, тако да је идеално за интерне белешке или задатке.

На пример, у README датотеци профила можете додати коментар који каже нешто попут тога да касније треба да проширите одељак „О мени“ или да треба да прегледате табелу застарелих технологија, а да нико ко посети профил то не види директно.

Још једна корисна функција је излазни знакови што би се нормално протумачило као Markdown. Ако треба да прикажете звездице, симболе хеш или друге симболе буквално без њиховог форматирања, једноставно испред сваког ставите обрнуту косу црту. Ово вам омогућава, на пример, да пишете изразе који укључују симболе листе без њиховог претварања у стварне листе.

Када прегледате датотеку са ознакама на ГитХабу, имате могућност да прелазите између рендерованог приказа и изворног кода помоћу дугмета на врху (или да је отворите у уређивачима као што је ЗаградеОнемогућавање интерпретације Markdown-а вам омогућава приступ типичним функцијама приказа кода као што су повезати одређене линијеОво је веома корисно када желите да укажете на тачан део README датотеке или било које .md датотеке.

На крају, запамтите да GitHub другачије обрађује преломе редова у коментарима (проблеми, захтеви за претрагу итд.) и у .md датотекама. У коментарима се преломи редова поштују директно, док у Markdown датотекама морате додати два размака на крају реда, обрнуту косу црту или тачку. да би се скок извршио унутар истог пасуса.

Листе, угнежђене листе и листе обавеза

Листе су један од најчешће коришћених елемената у Markdown-у, како на GitHub-у тако и на Reddit-у. Можете креирати листе неуређен стављањем цртице, звездице или знака плус испред сваке ставке листе. Сви ови знакови се приказују слично као тачке.

Да бисте генерисали листе наредиоСваки ред је нумерисан бројем праћен тачком и размаком. Иако редослед бројева не мора бити савршен (GitHub га обично поново израчунава), добра је идеја одржавати доследну нумерацију како би изворни код био читљив.

Угнежђене листе се креирају једноставним додавањем увлачења ставкама испод њих. У монопросторним едиторима као што су Сублиме ТекстЈедноставно поравнајте угнежђене маркере листе визуелно испод првог карактера текста у родитељском елементу. У контекстима као што је уређивач коментара на GitHub-у, где фонт није монопросторан, пребројте број карактера испред текста и користите тај број размака за увлачење.

Такође можете направити више нивоа угнежђивања, све док одржавате доследност у броју размака. За веома сложене листе, овај систем захтева мало вежбе, али када га једном савладате, веома је брзо применити.

ГитХаб такође нуди листе обавезаОво је веома корисно за проблеме, захтеве за преузимање и документацију. Креирају се тако што се испред цртице стави размак и пар угластих заграда са размаком или „x“ унутра: за задатке који чекају на извршење и за завршене задатке. Ове листе се приказују са пољима за потврду која се могу означити или уклонити из интерфејса.

Ако текст ставке листе обавеза почиње заградама, мора се избећи обрнутом косом цртом како би се избегла забуна у парсеру. То је мали детаљ, али важан када се пишу описи који почињу са нечим попут „(Опционо)“ или слично.

Помињања, референце и емоџији на ГитХабу

Једна од предности писања у Markdown-у на GitHub-у је могућност коришћења помиње Директне поруке корисницима и тимовима на платформи. Једноставно откуцајте @, а затим корисничко име или име тима, и GitHub ће послати обавештење том налогу, скрећући њихову пажњу на разговор.

Када укуцате симбол @, GitHub приказује листу корисника и тимова повезаних са репозиторијумом или нити, а ви можете филтрирати ову листу док куцате. Користите тастере са стрелицама и притисните Enter или Tab да бисте прихватили предлоге. За тимове користите формат @организација/назив-тима и сви чланови тима ће бити претплаћени на нит.

Поред помињања, GitHub олакшава проблеми са референцама и захтеви за повлачење Једноставно откуцајте # праћено бројем или делом наслова. Појавиће се листа предложених резултата, коју можете попунити на исти начин као и са помињањима. Ово знатно убрзава навигацију између повезаних разговора.

Ако ваш репозиторијум има конфигурисане прилагођене аутоматски повезане референце, одређене екстерне нотације (као што су JIRA или Zendesk ID-ови тикета) такође могу бити аутоматски конвертоване у кратке линкове. Ово подешавање захтева администраторске привилегије, али када се једном омогући, омогућава дељење података између система уз минималан напор.

Коначно, GitHub подржава емоџије путем кода: унесите двотачку, затим име емоџија и завршите са још једном двотачком. Када почнете да куцате, појављује се листа предлога, које можете прихватити помоћу Tab или Enter. Укључивање емоџија у ваше коментаре помаже да им се да људскији додир, све док их не претерујете са коришћењем у формалној документацији.

Фусноте и напредни садржај

ГитХаб такође подржава Фусноте Коришћење синтаксе засноване на заградама и идентификатора са испреплетеним знаком. На месту где желите референцу, убацујете нешто попут , а на крају документа дефинишете текст те напомене са истом ознаком, након чега следи двотачка и садржај.

Фусноте могу да се простиру преко више редова, а да би се наметнули преломи редова унутар фусноте, на крају реда се користе двоструки размаци, баш као и у главном делу Markdown-а. Приликом рендеровања, GitHub приказује надскрипт на тексту и листу фуснота на крају, са повратним линковима за навигацију између референци и фуснота.

Још једна напредна функција коју GitHub нуди је... упозорења О њима је већ било речи (НАПОМЕНА, САВЕТ, ВАЖНО, УПОЗОРЕЊЕ и ОПРЕЗ). Препоручљиво их је користити само када је то заиста неопходно и избегавати превелико набрајање како би се читалац не би преоптеретио. Не могу се угњеждити унутар других сложених елемената, па је пажљиво планирање њиховог постављања неопходно.

Коначно, можете замолити GitHub да привремено сакрије делове рендерованог Markdown-а тако што ће их умотати у HTML коментаре или да игнорише обраду одређених знакова обрнутим косим цртама. Ово је посебно корисно када документујете Маркдаунова сопствена синтакса И потребно је да прикажете примере онаквима какви јесу, без тумачења.

Маркдаун на Редиту: Снумарк и режим уређивања

Редит је платформа за дискусију где је готово свака тема добродошла, организована у подреддите. Што се тиче форматирања, нуди два едитора: један за обогаћени текст који је визуелнији и други за обичан текст заснован на Маркдауну. Ако желите да радите брзо и да имате прецизну контролу над резултатом, требало би да користите опцију Маркдаун.

Подразумевано, Редит обично активира уређивач обогаћеног текста, тако да да бисте прешли на режим означавања, морате да кликнете на опцију Режим маркирања унутар текстуалног поља објаве или коментара. Одатле можете директно користити Snoomark синтаксу.

Ако желите да се Markdown едитор увек учитава, требало би да одете у корисничка подешавања, уђете у одељак Подешавања фида и активирате опцију Подразумевано за markdownНа овај начин, сваки пут када почнете да пишете објаву или коментар, Markdown едитор ће се аутоматски отворити без потребе да га ручно мењате.

Редит подржава већину основних и напредних функција Маркдауна: наслове, подебљана и курсивна слова, листе, цитате, блокове кода, линкове и неке сопствене додатке попут спојлера. Међутим, има значајне недостатке у поређењу са ГитХабом, посебно у руковање сликамашто доста зависи од контекста и типа уредника.

Синтакса коју подржава Reddit и спојлери

Варијанта Snoomark-а коју користи Reddit укључује многе заједничке елементе са GitHub-ом, тако да ако већ познајете Markdown за репозиторијуме, преношење тог знања у Reddit окружење је прилично једноставно. Можете користити наслове за структурирање дугих објава, нумерисане или листе са ознакама, цитате за одговор другим корисницима и блокове кода када желите да прикажете команде или техничке исечке.

Једна од значајних разлика је начин на који Редит поступа са ликИако се у многим случајевима слике отпремају преко графичког интерфејса, а не директно помоћу Markdown синтаксе, механизам који обрађује текстуални садржај је и даље Snoomark, тако да је форматирање око тих слика засновано на Markdown-у.

Редит, с друге стране, додаје додатни елементи који нису део стандардне спецификације, као што су спојлери. Они вам омогућавају да сакријете текст иза слоја који корисник може да открије једним кликом. Технички, када Редит обрађује спојлер, он га трансформише у комбинацију HTML-а, CSS класа и JavaScript-а специфичног за платформу.

Добијена HTML репрезентација спојлера укључује обрађиваче који контролишу када се садржај приказује или сакрива, и док би се теоретски нешто слично могло написати обичним HTML-ом, на Редиту то зависи од његове интерне имплементације. Важно за вас као корисника је да приликом писања користите само специфичну синтаксу спојлера коју пружа едитор, и Снумарк је задужен за превод до одговарајуће структуре.

Укратко, Snoomark наслеђује многа понашања од GitHub Flavored Markdown-а, али усмерена ка потребама дискусионе заједнице, а не пројектне документације. Упркос томе, суштина остаје иста: обичан текст са једноставним симболима трансформисан у структуриран и читљив садржај.

Савладавање Markdown синтаксе на GitHub-у и Reddit-у чини писање техничке документације, отварање добро објашњених проблема, остављање јасних коментара на захтеве за преузимање и учешће у Reddit дискусијама много ефикаснијим. Уз неколико кључних правила – наслове, нагласак, листе, цитате, блокове кода, линкове, слике и специфичне трикове попут табела, детаља који се могу склопити, упозорења, фуснота и спојлера – можете прећи са писања обичног текста на креирање чист, скенљив и професионалан садржај без додиривања иједног дугмета миша.