Współtwórz przy użyciu GitHub Codespaces

Usługa GitHub ma funkcję o nazwie Codespaces , której można użyć do współtworzenia dokumentacji programu PowerShell bez konieczności instalowania ani konfigurowania dowolnego oprogramowania lokalnie. W przypadku korzystania z przestrzeni kodu uzyskasz te same narzędzia do tworzenia, których zespół używa do pisania i edytowania.

Możesz użyć przestrzeni kodu w przeglądarce, tworząc swój wkład w programie VS Code hostowanym przez Internet. Jeśli masz zainstalowany lokalnie program VS Code, możesz również nawiązać połączenie z Codespace.

Dostępne narzędzia

Jeśli używasz przestrzeni kodu do współtworzenia dokumentacji programu PowerShell, edytor ma już dostępne następujące narzędzia:

  • Markdownlint do sprawdzania składni Markdowna.
  • cSpell do sprawdzania pisowni.
  • Vale do sprawdzania Twojej prozy.
  • Pakiet Learn Authoring Pack do wstawiania składni specyficznej dla platformy, podglądu Twojego wkładu i nie tylko.
  • Rozszerzenie Reflow Markdown do opakowywania języka Markdown zgodnie z potrzebami, co ułatwia odczytywanie i edytowanie.
  • Rozszerzenie Table Formatter do sprawiania, aby Twoje tabele były bardziej czytelne, bez konieczności ręcznego wyrównywania kolumn.
  • Rozszerzenie change-case do zmiany wielkości liter w nagłówkach i prozie.
  • Rozszerzenie GitLens do przeglądania zmian plików historycznych.
  • Rozszerzenie programu PowerShell umożliwiające interaktywne tworzenie przykładów PowerShella.
  • Śledzenie Gremlins dla programu Visual Studio Code do znajdowania problematycznych znaków w Markdown.

Koszt

Usługi GitHub Codespaces można używać bezpłatnie do 120 godzin na miesiąc. Miesięczne użycie jest obliczane we wszystkich repozytoriach, a nie tylko w dokumentacji.

Aby uzyskać więcej informacji na temat cen, zobacz About billing for GitHub Codespaces (Informacje o rozliczeniach dla usługi GitHub Codespaces).

Wskazówka

Jeśli masz doświadczenie w korzystaniu z kontenerów i Docker, możesz osiągnąć podobne środowisko, działając z narzędziem devcontainer określonym dla repozytoriów dokumentacji programu PowerShell. Korzystanie z devcontainers nie wiąże się z kosztami. Aby uzyskać więcej informacji, zobacz samouczek Dev Containers.

Tworzenie usługi GitHub Codespace

Aby utworzyć usługę GitHub Codespace na potrzeby współtworzenia dokumentacji programu PowerShell, wykonaj następujące kroki:

  1. Otwórz https://github.com/codespaces w przeglądarce.
  2. Wybierz przycisk "Nowa przestrzeń kodu" w prawym górnym rogu strony.
  3. Na stronie "Utwórz nową przestrzeń kodu" wybierz przycisk "Wybierz repozytorium" i wpisz nazwę repozytorium, do którego chcesz współtworzyć, na przykład MicrosoftDocs/PowerShell-Docs.
  4. Pozostaw wartości domyślne wszystkich pozostałych ustawień.
  5. Wybierz przycisk "Utwórz przestrzeń kodu".

Po wykonaniu tych kroków usługa GitHub utworzy nową przestrzeń kodu dla tego repozytorium i skonfiguruje ją dla Ciebie. Gdy przestrzeń kodu jest gotowa, strona zostanie odświeżona i wyświetli interfejs użytkownika edytora sieci Web dla przestrzeni kodu. Interfejs użytkownika jest oparty na programie VS Code i działa w taki sam sposób.

Otwieranie usługi GitHub Codespace

Aby otworzyć aplikację GitHub Codespace w przeglądarce, wykonaj następujące kroki:

  1. Otwórz https://github.com/codespaces w przeglądarce.
  2. Strona wyświetla listę twoich obszarów Codespaces. Znajdź utworzoną przestrzeń kodu dla repozytorium, do którego chcesz współtworzyć, i wybierz ją.

Po wybraniu przestrzeni kodu usługa GitHub otworzy ją w tym samym oknie. Z tego miejsca możesz zacząć się przyczyniać.

Aby otworzyć usługę GitHub Codespace w programie VS Code, wykonaj kroki opisane w artykule Using GitHub Codespaces in Visual Studio Code (Korzystanie z usługi GitHub Codespaces w programie Visual Studio Code).

Tworzenie w środowisku GitHub Codespace

Po otwarciu usługi GitHub Codespace w przeglądarce lub programie VS Code, proces współtworzenia dokumentacji pozostaje taki sam.

W pozostałej części tego artykułu opisano wybór zadań, które można wykonać w usłudze GitHub Codespace podczas pisania lub edytowania wkładu.

Jeśli chcesz przekształcić link wbudowany, na przykład , w link referencyjny, taki jak [some text](destination.md)[some text][01], wybierz miejsce docelowe linku w edytorze. Następnie możesz wykonać następujące czynności:

  1. Kliknij prawym przyciskiem myszy miejsce docelowe linku i wybierz pozycję "Refaktoryzacja..." w menu kontekstowym.
  2. Naciśnij Ctrl+Shift+R.

Każda akcja wywołuje menu kontekstowe refaktoryzacji. Aby zastąpić element (destination.md) w linku elementem [def], wybierz pozycję Wyodrębnij definicję linku w menu kontekstowym. Możesz zmienić nazwę definicji, wpisując nową nazwę.

W dokumentacji programu PowerShell używamy dwucyfrowych definicji linków numerycznych, takich jak [01] lub [31]. Używaj tylko definicji linków referencyjnych w artykule i dokumentacji koncepcyjnej. Nie używaj definicji linków referencyjnych w dokumentacji cmdletów.

Poprawianie błędów stylu prozy

Podczas przeglądania artykułu w przestrzeni kodu Vale automatycznie sprawdza artykuł po pierwszym otwarciu i za każdym razem, gdy go zapiszesz. Jeśli Vale znajdzie jakiekolwiek naruszenia stylu, wyróżnia je w dokumencie kolorowymi falistymi podkreśleniami.

Zatrzymaj wskaźnik myszy na naruszeniu, aby wyświetlić więcej informacji na jego temat.

Aby otworzyć stronę internetową objaśniającą regułę, wybierz nazwę reguły w informacjach o aktywowaniu wskaźnika myszy. Aby otworzyć regułę i przejrzeć jej implementację, wybierz nazwę pliku reguły (kończącą się na )..yml

Jeśli reguła obsługuje szybką poprawkę, możesz wybrać opcję "Szybka poprawka..." w informacjach po najechaniu kursorem na naruszenie i zastosować jedną z sugerowanych poprawek, wybierając ją z menu kontekstowego. Możesz również nacisnąć Ctrl+. Gdy kursor znajduje się na wyróżnionym problemie, aby zastosować szybką poprawkę, jeśli reguła ją obsługuje.

Jeśli reguła nie obsługuje szybkich poprawek, przeczytaj komunikat reguły i napraw ją, jeśli to możliwe. Jeśli nie masz pewności, jak to naprawić, edytorzy mogą zasugerować coś podczas przeglądania pull requestu.

Rozwiązywanie problemów ze składnią

Podczas przeglądania artykułu w swojej przestrzeni kodowej Markdownlint automatycznie sprawdza artykuł po jego otwarciu i podczas wpisywania. Jeśli Markdownlint znajdzie jakiekolwiek problemy ze składnią, wyróżnia je w dokumencie kolorowymi podkreśleniami.

Zatrzymaj wskaźnik myszy na naruszeniu, aby wyświetlić więcej informacji na jego temat. Aby otworzyć stronę internetową objaśniającą regułę, wybierz identyfikator reguły w informacjach o aktywowaniu wskaźnika myszy.

Jeśli reguła obsługuje szybką poprawkę, możesz wybrać opcję "Szybka poprawka..." w informacjach po najechaniu kursorem na naruszenie i zastosować jedną z sugerowanych poprawek, wybierając ją z menu kontekstowego. Możesz również nacisnąć Ctrl+. Gdy kursor znajduje się na wyróżnionym problemie, aby zastosować szybką poprawkę, jeśli reguła ją obsługuje.

Jeśli reguła nie obsługuje szybkich poprawek, przeczytaj komunikat reguły i napraw ją, jeśli to możliwe. Jeśli nie masz pewności, jak to naprawić, edytorzy mogą zasugerować coś podczas przeglądania pull requestu.

Poprawki można również zastosować do wszystkich naruszeń składni w artykule. Aby to zrobić, otwórz paletę poleceń i wpisz Fix all supported markdownlint violations in the document. Podczas wpisywania paleta poleceń filtruje dostępne polecenia. Wybierz polecenie "Napraw wszystkie obsługiwane błędy markdownlint w dokumencie". Gdy to zrobisz, markdownlint aktualizuje dokument, aby rozwiązać wszelkie naruszenia, dla których ma on szybką poprawkę.

Formatowanie tabeli

Aby sformatować tabelę w Markdown, umieść kursor w tej tabeli. Otwórz paletę poleceń i wyszukaj Table: Format Current polecenie . Po wybraniu tego polecenia program aktualizuje język Markdown dla tabeli w celu wyrównania i wypełnienia tabeli w celu zwiększenia czytelności.

Konwertuje tabelę zdefiniowaną w następujący sposób:

| foo | bar | baz |
|:--:|:--|-:|
| a | b | c |

W tym celu:

|  foo  | bar  | baz  |
| :---: | :--- | ---: |
|   a   | b    |    c |

Wstaw alert

Dokumentacja używa alertów, aby uczynić informacje bardziej zauważalnymi dla czytelnika.

Aby wstawić alert, możesz otworzyć paletę poleceń i wyszukać Learn: Alert polecenie. Po wybraniu tego polecenia zostanie otwarte menu kontekstowe. Wybierz typ alertu, który chcesz dodać. Gdy to zrobisz, polecenie wstawia znacznik Markdown alertu w miejscu kursora w dokumencie.

Tworzenie nagłówka z zastosowaniem wielkich liter jak w zdaniach

Aby zmienić wielkość liter w nagłówku, zaznacz tekst nagłówka z wyjątkiem początkowych symboli #, które określają poziom nagłówka. Gdy zaznaczysz tekst, otwórz paletę poleceń i wyszukaj polecenie Change case sentence. Po zaznaczeniu tego polecenia zmienia wielkość liter zaznaczonego tekstu.

Można również użyć poleceń zmiany wielkości liter dla dowolnego tekstu w dokumencie.

Otwórz paletę poleceń

Paleta poleceń programu VS Code umożliwia uruchamianie wielu przydatnych poleceń.

Aby otworzyć paletę poleceń w interfejsie użytkownika, wybierz pozycję "Widok" na górnym pasku menu. Następnie wybierz pozycję "Paleta poleceń..." w menu kontekstowym.

Aby otworzyć paletę poleceń za pomocą klawiatury, naciśnij kombinację dla systemu operacyjnego:

  • Windows i Linux: Ctrl+Shift+P
  • macOS: Cmd+Shift+P

Podgląd udziału

Aby wyświetlić podgląd swojej kontrybucji, otwórz paletę poleceń i wyszukaj polecenie Markdown: Open Preview. Po wybraniu tego polecenia program VS Code otworzy podgląd aktywnego dokumentu. Styl wersji zapoznawczej jest zgodny z platformą Learn.

Uwaga

Linki względne do witryny i linki do odniesień krzyżowych nie działają w podglądzie.

Przepełnij ponownie zawartość

Aby ograniczyć długość wiersza akapitu w dokumencie, umieść kursor na akapicie. Następnie otwórz paletę poleceń i wyszukaj Reflow Markdown polecenie . Po wybraniu polecenia aktualizuje długość wiersza bieżącego akapitu do skonfigurowanej długości. W przypadku naszych repozytoriów ta długość wynosi 99 znaków.

W przypadku używania tego polecenia dla cytatów blokowych, upewnij się, że akapit w cytacie blokowym, który formatujesz, jest otoczony pustymi wierszami. W przeciwnym razie polecenie zmienia każdy akapit razem.

Ostrożność

Nie używaj tego polecenia podczas edytowania artykułów. Wiersze w tych dokumentach nie mogą być dłuższe niż 80 znaków. Obecnie nie ma możliwości skonfigurowania różnych długości wierszy według folderu lub nazwy pliku, więc funkcja reflow nie działa w przypadku dokumentów typu 'about article'.

Przejrzyj wszystkie problemy w dokumencie

Aby przejrzeć wszystkie naruszenia reguł składni i stylu w dokumencie, otwórz Widok problemów.

Aby otworzyć widok Problemy w interfejsie użytkownika, wybierz pozycję "Widok" na górnym pasku menu. Następnie wybierz pozycję "Problemy" w menu kontekstowym.

Aby otworzyć widok Problemy za pomocą klawiatury, naciśnij kombinację dla systemu operacyjnego:

  • Windows i Linux: Ctrl+Shift+M
  • macOS: Cmd+Shift+M

Widok problemów wyświetla wszystkie błędy, ostrzeżenia i sugestie dotyczące otwartego dokumentu. Wybierz problem, aby przewinąć go do dokumentu.

Problemy można filtrować według typu lub dopasowania tekstu.

Aktualizowanie metadanych ms.date

Aby zaktualizować ms.date metadane artykułu, otwórz paletę poleceń i wyszukaj Learn: Update "ms.date" Metadata Value polecenie . Po wybraniu polecenia aktualizuje metadane do bieżącej daty.

Dodatkowe zasoby

Zadania i polecenia opisane w tym artykule nie obejmują wszystkiego, co można zrobić za pomocą programu VS Code lub zainstalowanych rozszerzeń.

Aby uzyskać więcej informacji na temat korzystania z programu VS Code, zobacz następujące artykuły:

Aby uzyskać więcej informacji na temat zainstalowanych rozszerzeń, zobacz ich dokumentację:

  • Last updated on