Dokumentacje piszę każdy, niezależnie czy jesteś Developerem, Adminem, DevOpse czy pasjonatem PowerShella 🙂 . Do dokumentacji mamy różne podejście, tworzymy w różny sposób i w różnych narzędziach. W tym celu można wykorzystywać Microsoft Word, Open Office lub dokumenty Docs z pakietu G-Suite. Elementem wspólnym tych rozwiązań jest „klikalny” edytor tekstu tzw. WYSIWYG.

Natomiast w tym wpisie, chciałbym Ci zaproponować alternatywę w postaci Markdown, który świetnie się sprawdzi w utrzymaniu w dokumentacji. Pokaże Ci również polecenia PowerShell, które będą przydatne zarówno do przeglądania takich plików, jak i tworzenia.

Czym jest Markdown?

Markdown to prosty język znaczników stworzony w 2004 roku przez Johna Grubera. Znaczniki Markdown dodajesz do zwykłego tekstu w celu jego formatowania. Znaczniki przekładają się na wizualizację dokumentu w momencie konwersji z pliku płaskiego do formatu HTML.

Takie podejście różni się od tego co znamy, chociażby np. z edytora Microsoft Word, gdzie po pierwsze zmiany formatowania wyklikujemy, po drugie, zmiany są widoczne natychmiastowo.

Być może zastanawiasz się, dlaczego miałbyś używać Markdown zamiast dobrze znanego edytora WYSIWYG.

Zalety Markdown

Po pierwsze Markdown nie potrzebuje, żadnego komercyjnego, płatnego narzędzia. Wizualizacja plików jest wspierana przez większość popularnych narzędzi takich jak Visual Studio Code, Notepad++ (po dodaniu rozszerzeń), GitHub, Bitbucket, GitLab czy PowerShell.

Po drugie, treść utrzymujesz w zwykłym pliku, tylko z dodatkiem znaczników, który sam w sobie już jest czytelny i zrozumiały. Natomiast po konwersji staje się odpowiednio sformatowanym dokumentem, który nadaje się do prezentacji nie tylko dla gości z IT.

Dodatkowo pisanie za pomocą Markdown już, po krótkiej „chwili” jest łatwe, szybkie i intuicyjne.

Sama idea tego rozwiązania jest świetna:

Markdown ma być tak łatwy, jak tylko to możliwe zarówno do odczytania i do napisania.

Też, żeby nie było, Markdown nie nadaje się do wszystkiego, ale na pewno jest powszechnie używany do tworzenia stron internetowych, notatek (ten wpis też napisałem w Markdown), książek, wiadomości e-mail i dokumentacji technicznej.

Podstawowe elementy Markdown

Poniżej przykładowe znaczniki Markdown, które są wystarczające na początek. W 98% przypadkach nie potrzebuję niczego więcej.

# Nagłówek pierwszego poziomu
 
## Nagłówek drugiego
 
### Trzeciego poziomu (i tak mogłoby być do 6 -> ######)
 
Aby utworzyć akapity, użyj pustej linii, aby oddzielić jeden lub więcej wierszy tekstu.
 
Czyli tutaj kolejny akapit
 
W ten sposób **pogrubimy** tekst, chyba, że chcemy coś *pochylić* lub coś ~~przekreślić~~ bo jest nieaktualne.
 
Poniżej jakaś lista (z linkami)
- [Basic Syntax](https://www.markdownguide.org/basic-syntax/)
- [Extended Syntax](https://www.markdownguide.org/extended-syntax/)
 
---
 
```powershell
# sposób na osadzanie kodu
Get-Command *Markdown* -CommandType Cmdlet
```
 
Nic nie stoi na przeszkodzie aby osadzić plik gif lub jpg.
 
![malo smieszne](https://media.giphy.com/media/aWPGuTlDqq2yc/giphy.gif)
 
Jeszcze jakiś cytat na koniec
 
> Markdown ma być tak łatwy jak tylko to możliwe zarówno do odczytania i do napisania.

Tak wygląda wizualizacja tego przykładu. Łatwe, proste i przyjemne.

powershell markdown

PowerShell i Markdown

Polecenia dla Markdown pojawiły się w PowerShell Core 6 (gdzieś od wersji 6.1) i naturalnie przeszły do PowerShell 7. Natomiast na próżno ich szukać w Windows PowerShell 5.1.

Convert-FromMarkdown

Za pomocą ConvertFrom-Markdown zmienisz ciąg znaków lub zawartość pliku na obiekt MarkdownInfo. Domyślnie polecenie wykonuję konwersję do HTML, który możemy później zapisać do pliku.

Natomiast po zastosowaniu przełącznika -AsVT100EncodedString, otrzymujemy obiekt z ciągiem znaków wraz z kodami specjalnymi VT100.

powershell markdown

Dzięki znakom specjalnym możliwa jest podstawowa wizualizacja w terminalu, po zastosowaniu…

Show-Markdown

Show-Markdown w przyjazny sposób wyświetli obiekt MarkdownInfo w przeglądarce internetowej (po użyciu przełącznika -UseBrowser) lub w terminalu za pomocą, wcześniej wspomnianego VT100.

Do tego polecenia możesz przekazać wyjściowy obiekt Convert-FromMarkdown lub wskazać bezpośrednią ścieżkę do pliku .md.

ConvertFrom-Markdown -Path C:\Users\Lenovo\Documents\Projekty\06_Blog\03_akademiapowershell_blog\new_blog\15_Markdown_wykorzystanie.md -AsVT100EncodedString | Show-Markdown
 
Show-Markdown -Path C:\Users\Lenovo\Documents\Projekty\06_Blog\03_akademiapowershell_blog\new_blog\15_Markdown_wykorzystanie.md
 
Show-Markdown -Path C:\Users\Lenovo\Documents\Projekty\06_Blog\03_akademiapowershell_blog\new_blog\15_Markdown_wykorzystanie.md -UseBrowser
powershell markdown

Kowersja VT100

Dodawane kody specjalne (znaki ucieczki – Escape) podczas konwersji umożliwiają kodowanie kolorów oraz odpowiednią wizualizację w terminalu.

Oprócz wcześniej przedstawionych poleceń, Get-MarkdownOption zwróci zdefiniowane kolory i style wizualizacji w konsoli. Jeśli chciałbyś zmienić domyślny sposób prezentacji, wykorzystaj polecenie Set-MarkdownOption.

Moduł PSToolBox

PSScriptTools to zbiór kilkunastu użytecznych funkcji autorstwa Jeff Hicks. W tym module znalazła się prosta funkcja ConvertTo-Markdown, dzięki której utworzysz i osadzisz wyniki swoich poleceń w plikach Markdown.

Get-Service -DisplayName *sql* | ConvertTo-Markdown -Title 'Sql Server Processes' -PreContent "Wszystkie procesy Sql Server na $($env:ComputerName)"
 
    <#
    # Sql Server Processes
 
    Wszystkie procesy Sql Server na IT-MN-M
 
    ```text
 
    Status   Name               DisplayName
    ------   ----               -----------
    Running  MSSQL$MSSQLSERVER… SQL Server (MSSQLSERVER15)
    Running  MSSQLFDLauncher    SQL Full-text Filter Daemon Launcher …
    Running  MSSQLSERVER        SQL Server (MSSQLSERVER)
    Stopped  SQLAgent$MSSQLSER… SQL Server Agent (MSSQLSERVER15)
    Stopped  SQLBrowser         SQL Server Browser
    Stopped  SQLSERVERAGENT     SQL Server Agent (MSSQLSERVER)
    Running  SQLTELEMETRY       SQL Server CEIP service (MSSQLSERVER)
    Running  SQLTELEMETRY$MSSQ… SQL Server CEIP service (MSSQLSERVER1…
    Running  SQLWriter          SQL Server VSS Writer
    ```
    #>
 
# lub
Get-Service -DisplayName *sql* | ConvertTo-Markdown -Title 'Sql Server Processes' -PreContent "Wszystkie procesy Sql Server na $($env:ComputerName)"  | Show-Markdown -UseBrowser
powershell markdown

Podsumowanie

Lubię Markdown i zadziwiająco często z niego korzystam. Nie mówię, że sprawdzi się wszędzie, jednak dla dokumentacji utrzymywanej w systemie kontroli wersji, ciężko znaleźć lepsze rozwiązanie.

Kwestie wizualizacji plików Markdown za pomocą PowerShell bardziej traktuję jako miły dodatek, jednak samo tworzenie ma spory potencjał.

Do wizualizacji najczęściej wykorzystuję Visual Studio Code wraz z odpowiednim dodatkiem, np. Markdown Preview Github Styling.

22 Najważniejsze Wskazówki Pisania Skryptów PowerShell

Mateusz Nadobnik

Zachwycony językiem skryptowym Windows PowerShell. Swoją wiedzę, doświadczenia i spostrzeżenia opisuję na blogu.

read more