Markdown

Magandang araw, mga kasamahan! Pagkatapos ng mahabang paglalakbay sa pag-aaral, nais ng lahat na ipakita sa employer ang kanilang mga bunga, at ipakita lamang sa kanila mula sa pinakamahusay, propesyonal na panig, tama ba? Sa tingin ko oo. Samakatuwid, bilang karagdagan sa isang wastong disenyo at ipinatupad na proyekto, kailangan natin itong gawing pormal. Hindi babasahin ng employer ang lahat ng iyong project code para maunawaan kung tungkol saan ito at kung ano ang kasama dito? Sa artikulong ito, sa wakas ay ibubuod natin ang naunang dalawa, katulad ng: Continuous Integration at Code Coverage , at ipaunawa sa amin sa "harap" na sheet ng open-source na proyekto kung ano ang ginamit namin sa aming proyekto at kung ano ang kinakatawan nito. Ngayon ay makikipag-usap kami sa iyo tungkol sa Markdown, tanungin ang aming mga paboritong tanong: "Ano ito?" at "Bakit ito?", alamin natin kung saan ito ginagamit at kung paano ito gagawin. Magkakaroon pa ng halimbawa, ipapatupad namin ito sa aming open-source na proyekto . Kaya, tayo na!

Ano ang "Markdown"?

Dahil ikaw at ako ay mga programmer, agad kaming pupunta sa Google at bubuksan ang unang link ng Wiki , na nagsasabing: Ang Markdown ay isang magaan na markup language na nilikha na may layuning magsulat ng pinakanababasa at madaling i-edit na teksto, ngunit angkop para sa conversion sa mga wika para sa mga advanced na publikasyon (HTML , Rich Text at iba pa). Dito, sa totoo lang, wala akong gaanong idadagdag, sa tingin ko ito ay halos perpektong paliwanag.

Bakit natin kailangan ang "Markdown" na ito?

Sa totoo lang, hindi naman masama kung wala ito :D Ngunit tandaan natin ang ating layunin: magsulat ng isang karampatang template ng proyekto na mayroon nang Continuous Integration at may mga istatistika ng Code Coverage sa mapagkukunan ng Codecov. Bakit ko nabanggit ito? Bukod dito, papayagan kami ng Markdown na kumuha ng data mula sa mga mapagkukunang ito at ibigay ang data mismo, o mga badge na magre-redirect sa amin kung saan kailangan naming makuha ang impormasyong ito. Maginhawang ilagay ang lahat sa isang pahina ng "pamagat", sa halip na nakakalat sa iba't ibang lugar, hindi ba?

Saan ito ginagamit?

Ang sinumang nag-upload ng anuman sa kanilang mga proyekto sa GitHub kahit isang beses ay nakakaalam na ang GitHub ay patuloy na gustong imbitahan ka na lumikha ng README file: Ano ang extension ng file na ito? Tama, alam ni Bolt ang Markdown! Tulad ng alam na natin, ang file na ito ay napakadaling nababagay sa maraming mga format at na-convert sa HTML na kailangan natin. Ngunit maglaan tayo ng oras at huwag magmadaling idagdag ito kaagad sa GitHub.

Paano ito gagawin?

Una, tulad ng napansin mo, maaari naming idagdag ito nang direkta sa GitHub at gagana ito! Ngunit hindi namin kailangang idagdag ito palagi sa isang proyekto, halimbawa. O halimbawa gusto naming mag-isip nang higit pa tungkol sa kung paano namin ito nilikha. At dito hindi na angkop sa amin ang GitHub. At sa pangkalahatan, maaari tayong lumikha ng mga Markdown file hindi lamang para sa layuning itulak ang mga ito sa GitHub. Pangalawa, maaari naming gawin ito nang direkta sa pamamagitan ng IDEA, na kung ano mismo ang gagawin namin, ngunit hindi kaagad, sa kadahilanang bakit kailangan namin ng isang malakas na kapaligiran sa pag-unlad upang magsulat ng isang maliit na file? Dito inirerekumenda ko ang pag-browse sa catalog ng madali, at hindi ganoon kadali, mga editor ng Markdown file. Para sa aking sarili, pinili ko ang Haroopad , ito ay napaka-simple, naa-access, may instant na representasyon ng iyong isinusulat (ginawa rin ng IDEA), at may pahiwatig ng syntax. Ganito ang hitsura ng editor window: Dito ko binuksan ang isang ready-made README.md ng isa sa aking mga proyekto. Sa kaliwa ay isang cheat sheet, sa kanan ay isang display, sa gitna ay teksto. Ang lahat ay napaka-primitive at simple. Makakakita ka rin ng mga badge, na pag-uusapan natin sa ilang sandali. Yaong mga pumili ng ibang paraan ng pagsulat ng mga file na ito - huwag maalarma, ang lahat ay naiiba ay ang graphical na interface. Ang text, syntax at display ay mananatiling hindi magbabago. Halimbawa Ang gawain ay napaka-simple: isulat ang README.md upang naglalaman ito ng: impormasyon tungkol sa proyekto (kabilang ang mga badge), impormasyon tungkol sa pag-import ng proyekto, impormasyon tungkol sa pagpapatupad ng proyekto, impormasyon tungkol sa mga contact ng may-akda. Ang lahat ay napaka-simple at primitive, tulad ng nasabi ko na. Bumaba tayo sa negosyo.

1. Sumulat tayo ng isang pamagat - ang pangalan ng aming proyekto.

   Ang pangunahing at pinakamalaking heading ay nilikha gamit ang hash operator na " # " at pagkatapos ay isusulat ang pamagat. Sa kaso natin:

   # ForJavaRushPublication

2. Pagkatapos ay magsusulat kami ng bahagyang mas maliit na pamagat, at isusulat namin ang "Impormasyon ng Proyekto". Ang mas maliit na header ay nauunahan ng higit pang " # ":

   ## Information

   At pagkatapos ay magsusulat kami ng impormasyon tungkol sa proyekto.

3. Ipasok natin ang mga link sa ating mga artikulo. Ginagawa ito nang napakasimple, at kung gagamit ka ng Haroopad, i-type lang ang cheat sheet at ang template ay ipapasok mismo. Ang syntax ay: " [text](url) ";

4. Maglagay tayo ng mga badge. Tingnan natin ang mas malapit dito.

   Una, ayusin natin ang mga ito sa anyo ng isang mesa, para sa kagandahan. Magkakaroon ng 2 column at 2 column. Magiging ganito ang hitsura ng syntax:

   At ang resulta ay magiging ganito:

   Susunod, maglalagay kami ng mga hyperlink sa aming mga badge, ngunit saan namin sila makukuha? Ipinakita ko sa nakaraang artikulo kung saan kukuha ng Codecov, ngunit hindi ko binanggit kung alin ang makukuha. Dahil mayroon kaming Markdown file, kailangan din namin ng Markdown Badge:

   Kopyahin lang ito at i-paste sa isang column sa aming Markdown. Ngunit huwag kalimutan na lumitaw ang Codecov sa sangay ng JaCoCo, ngunit hindi sa master, kaya kailangan mong iwasto ito nang manu-mano. Ang Travis CI Badge ay direktang kinuha sa tapat ng pangalan ng proyekto, kung saan ang build log ay:

   Pinipili namin ang badge, at pagkatapos ay mag-pop up ang window ng mga setting:

   Talagang pipiliin namin ang Markdown, at ang sangay na kailangan mo. Gagawa ako ng README.md para sa dalawang sangay, at bahagyang magkakaiba ang mga ito, dahil hindi ko pa naipapatupad ang Codecov sa master branch.




5. Sumulat tayo ng impormasyon kung paano i-import o i-clone ang proyektong ito. Hindi ko ipapaliwanag kung paano ito gagawin, ngunit mababasa mo ito sa aking README.md. Magsusulat kami tungkol sa mga teknolohiyang ginamit namin sa aming proyekto, na naglalagay ng mga link sa kanila. Gayunpaman, ito ay isang proyektong pang-edukasyon. Well, isulat natin ang impormasyon ng contact.




6. Ang aming Markdown ay handa na. Ang kailangan lang naming gawin ay idagdag ito sa aming proyekto at tapos na kami. Ngunit hindi lahat ng sabay-sabay! Buksan natin ang aming IDEA, at sa Mga Plugin, tinitingnan namin kung mayroon kang Markdown Support:

   Mayroon akong Ultimate IDEA, kaya mayroon akong lahat, maaaring hindi naka-install ang iyong plugin bilang default, ngunit kapag lumikha ka ng isang file na may extension ng md, dapat kang ma-prompt na i-download ito. I-download at i-restart ang iyong IDEA.




7. Pagkatapos i-import ang Markdown na isinulat namin, buksan ito sa pamamagitan ng IDEA at i-edit ito kung kinakailangan. Ito ang hitsura nito sa pamamagitan ng IDEA:

   Push namin. Pagkatapos ay nakita namin na kapag nagbukas ng isang proyekto, ang impormasyon tungkol dito ay agad na na-load, ito ang aming README.md:

   Ngayon, kapag nag-click kami sa badge, maaari kaming tumalon diretso sa pagpupulong ng proyekto at makita kung ano ang mayroon kami doon at kung paano.




8. Gayon din ang gagawin ko para sa JaCoCo branch para maipakita ang Codecov Badge, dahil wala pa kaming README.md dito. Bilang resulta, mayroon na tayong dalawang badge:

   Ipinapakita ng Codecov ang porsyento ng saklaw ng code, at maaari rin itong mag-redirect sa amin sa page ng Codecov at magpakita ng detalyadong ulat sa saklaw ng code.

kapaki-pakinabang na mga link

• Ano ang sinasabi sa amin ng Wiki tungkol sa Markdown;
• Markdown Editors Directory ;
• Haroopad na inirerekomenda ko;
• Tungkol sa Markdown sa website ng JetBrains ;
• Markdown Navigator sa parehong JetBrains;
• Mga badge at lahat ng tungkol sa kanila. Dito maaari mong piliin ang estilo ng anumang badge at i-customize ito para sa iyong sarili;
• Paano i-upgrade ang iyong open-source na proyekto? Sasagutin din ng artikulong ito ;
• Nakaraang artikulo

Ibuod natin ang serye ng aking mga artikulo

1. Tiningnan namin kung ano ang CI, para saan ito at kung paano ito gamitin sa unang artikulo tungkol sa Continuous Integration ;
2. Naglaro kami sa CC at naunawaan kung ano ito at kung bakit ito kailangan sa ikalawang artikulo tungkol sa Code Coverage ;
3. At sa artikulong ito ay tiningnan natin kung ano ang Markdown, bakit ito kailangan at kung paano ito epektibong gamitin.

Salamat sa lahat sa pagbabasa ng tatlong mahabang artikulong ito, sana ay naging kapaki-pakinabang ang mga ito. Maaaring may mga pagkakamali at pagkukulang sa teksto. Salamat sa lahat para sa iyong pansin!