Przeczytaj w języku angielskim

Udostępnij za pośrednictwem


Współtworzenia dokumentacji urządzenia HoloLens

Witamy w dokumentacji HoloLens! Wszystkie artykuły tworzone lub edytowane w tym repozytorium będą widoczne dla opinii publicznej.

Dokumentacja urządzenia HoloLens została opublikowana w witrynie Microsoft Learn, która korzysta z języka Markdig z funkcjami języka Markdig o smaku gitHub. Zawartość edytowana w tym repozytorium jest formatowana w stylizowane strony, które są wyświetlane w /hololens.

Na tej stronie opisano podstawowe kroki i wskazówki dotyczące współtworzenia oraz linki do podstaw języka Markdown. Dziękujemy za twój wkład!

Dostępne repozytoria

Nazwa repozytorium Adres URL
HoloLens MicrosoftDocs/HoloLens
Rzeczywistość mieszana MicrosoftDocs/mixed-reality
Przewodnik entuzjastów VR MicrosoftDocs/mixed-reality/entuzjasty-guide

Przed rozpoczęciem

Jeśli jeszcze go nie masz, musisz utworzyć konto usługi GitHub.

Uwaga

Jeśli jesteś pracownikiem firmy Microsoft, połącz swoje konto GitHub z aliasem firmy Microsoft w portalu microsoft open source . Dołącz do "Microsoft" i "MicrosoftDocs" organizacji.

Podczas konfigurowania konta usługi GitHub zalecamy również stosowanie następujących środków ostrożności:

  • Utwórz silne hasło dla konta usługi GitHub.
  • Włącz uwierzytelnianie dwuskładnikowe.
  • Zapisz kody odzyskiwania w bezpiecznym miejscu.
  • Zaktualizuj ustawienia profilu publicznego .
    • Ustaw swoją nazwę i rozważ ustawienie publicznej poczty e-mail na Nie pokazuj mojego adresu e-mail.
    • Zalecamy przekazanie obrazu profilu, ponieważ miniatura jest wyświetlana w artykułach w witrynie Microsoft Learn, które współtworzysz.
  • Jeśli planujesz używać wiersza polecenia, rozważ skonfigurowanie programu Git Credential Manager dla systemu Windows. W ten sposób nie trzeba wprowadzać hasła za każdym razem, gdy tworzysz wkład.

System publikowania jest powiązany z usługą GitHub, dlatego te kroki są ważne. Zostaniesz wymieniony jako autor lub współautor każdego artykułu przy użyciu aliasu usługi GitHub.

Edytowanie istniejącego artykułu

Użyj następującego przepływu pracy, aby zaktualizować istniejącego artykułu za pośrednictwem usługi GitHub w przeglądarce internetowej:

  1. Przejdź do artykułu, który chcesz edytować w folderze "hololens".

  2. Wybierz przycisk edycji (ikona ołówka) w prawym górnym rogu.

    Edytowanie artykułu.

    Spowoduje to automatyczne rozwidlenie jednorazowej gałęzi z gałęzi domyślnej, main.

  3. Edytuj zawartość artykułu zgodnie z Podstawy języka Markdown.

  4. Zaktualizuj metadane w górnej części każdego artykułu:

    • tytuł: tytuł strony wyświetlany na karcie przeglądarki po wyświetleniu artykułu. Tytuły stron są używane do seo i indeksowania, więc nie zmieniaj tytułu, chyba że jest to konieczne (choć jest to mniej krytyczne przed upublicznienie dokumentacji).
    • opis: Napisz krótki opis zawartości artykułu, co zwiększa seo i odnajdywanie.
    • autor: jeśli jesteś głównym właścicielem strony, dodaj tutaj alias usługi GitHub.
    • ms.author: jeśli jesteś głównym właścicielem strony, dodaj tutaj alias firmy Microsoft (nie potrzebujesz @microsoft.com, tylko alias).
    • ms.date: zaktualizuj datę, jeśli dodasz główną zawartość do strony, ale nie w przypadku poprawek, takich jak wyjaśnienie, formatowanie, gramatyka lub pisownia.
    • słowa kluczowe: Pomoc słów kluczowych w optymalizacji wyszukiwarek (optymalizacja aparatu wyszukiwania). Dodaj słowa kluczowe oddzielone przecinkami i spacją, które są specyficzne dla artykułu, ale nie są znakiem interpunkcyjnym po ostatnim słowie kluczowym na liście. Nie musisz dodawać globalnych słów kluczowych, które mają zastosowanie do wszystkich artykułów, ponieważ są one zarządzane gdzie indziej.
  5. Po zakończeniu edycji artykułu przewiń w dół i wybierz pozycję Zaproponuj zmianę pliku.

  6. Na następnej stronie wybierz pozycję Utwórz żądanie ściągnięcia, aby scalić automatycznie utworzoną gałąź z gałęzią domyślną main.

  7. Powtórz powyższe kroki dla następnego artykułu, który chcesz edytować.

Zmiana nazwy lub usunięcie istniejącego artykułu

Jeśli zmiana zmieni nazwę lub usunie istniejący artykuł, pamiętaj, aby dodać przekierowanie. W ten sposób każda osoba mająca link do istniejącego artykułu nadal znajdzie się we właściwym miejscu. Przekierowania są zarządzane przez plik .openpublishing.redirection.json w katalogu głównym repozytorium.

Aby dodać przekierowanie do .openpublishing.redirection.json, dodaj wpis do tablicy redirections:

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • source_path to względna ścieżka repozytorium do starego artykułu, który usuwasz. Upewnij się, że ścieżka rozpoczyna się od zestawu dokumentów (w tym przypadku hololens) i zawiera rozszerzenie .md pliku.

  • redirect_url jest względnym publicznym adresem URL ze starego artykułu do nowego artykułu. Upewnij się, że ten adres URL nie zawiera .md i zaczyna się od /, ponieważ odnosi się do publicznego adresu URL, a nie ścieżki repozytorium. Łączenie z sekcją w nowym artykule przy użyciu #section jest dozwolone. W razie potrzeby możesz również użyć ścieżki bezwzględnej do innej witryny.

  • redirect_document_id wskazuje, czy chcesz zachować identyfikator dokumentu z poprzedniego pliku. Wartość domyślna to false. Użyj true, jeśli chcesz zachować wartość atrybutu ms.documentid z przekierowanego artykułu. Jeśli zachowasz identyfikator dokumentu, dane, takie jak widoki stron i rankingi, zostaną przeniesione do artykułu docelowego. Zrób to, jeśli przekierowanie jest przede wszystkim zmianą nazwy, a nie wskaźnikiem do innego artykułu, który obejmuje tylko część tej samej zawartości.

Jeśli dodasz przekierowanie, pamiętaj o usunięciu starego pliku.

Tworzenie nowego artykułu

Użyj następującego przepływu pracy, aby utworzyć nowe artykuły w repozytorium dokumentacji za pośrednictwem usługi GitHub w przeglądarce internetowej:

  1. Utwórz rozwidlenie od gałęzi domyślnej, main, microsoftDocs/hololens przy użyciu przycisku rozwidlenia w prawym górnym rogu.

    rozwidlenie gałęzi domyślnej, obecnie o nazwie

  2. W folderze "hololens" wybierz pozycję Utwórz nowy plik w prawym górnym rogu.

  3. Utwórz nazwę strony artykułu (użyj łączników zamiast spacji i nie używaj interpunkcji ani apostrofów) i dołącz ".md"

    Nadaj nowej stronie nazwę.

    Ważne

    Upewnij się, że utworzono nowy artykuł z poziomu folderu "hololens". Możesz to potwierdzić, sprawdzając ciąg "/hololens/" w nowym wierszu nazwy pliku.

  4. W górnej części nowej strony dodaj następujący blok metadanych:

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. Wypełnij odpowiednie pola metadanych zgodnie z opisem we wcześniejszej sekcji Edytowanie istniejącego artykułu.

  6. Pisanie zawartości artykułu przy użyciu podstaw języka Markdown.

  7. Dodaj sekcję ## See also w dolnej części artykułu z linkami do innych odpowiednich artykułów.

  8. Po zakończeniu wybierz pozycję Zatwierdź nowy plik.

  9. Wybierz nowe żądanie ściągnięcia i scal gałęzi głównej rozwidlenia z gałęzią MicrosoftDocs/hololens głównym (upewnij się, że strzałka wskazuje prawidłową lokalizację docelową).

    Utwórz żądanie ściągnięcia z rozwidlenia do dokumentów MicrosoftDocs/hololens.

Podstawy języka Markdown

Następujące zasoby pomogą Ci dowiedzieć się, jak edytować dokumentację przy użyciu języka Markdown:

Dodawanie tabel

Ze względu na styl tabel w środowisku Microsoft Learn nie będą miały obramowań ani stylów niestandardowych, nawet jeśli spróbujesz w tekście css. Wydaje się, że będzie działać przez krótki okres czasu, ale ostatecznie platforma usunie styl z tabeli. Więc zaplanuj z wyprzedzeniem i zachowaj proste tabele. Oto witryna, która ułatwia tabele języka Markdown: [Tables Generator]](https://www.tablesgenerator.com/markdown_tables).

Rozszerzenie Docs Markdown dla programu Visual Studio Code również ułatwia generowanie tabel, jeśli używasz Visual Studio Code (patrz poniżej) do edytowania dokumentacji.

Dodawanie obrazów

Musisz przekazać obrazy do folderu "hololens/images" w repozytorium, a następnie odwołać się do nich odpowiednio w artykule. Obrazy będą automatycznie wyświetlane w pełnym rozmiarze, co oznacza, że duże obrazy wypełnią całą szerokość artykułu. Zalecamy wstępne ustalanie rozmiaru obrazów przed ich przekazaniem. Zalecana szerokość wynosi od 600 do 700 pikseli, chociaż rozmiar powinien być większy lub wyłączony, jeśli jest to gęsty zrzut ekranu lub ułamek zrzutu ekranu, odpowiednio.

Ważne

Obrazy można przekazywać tylko do rozwidlenia przed scaleniem. Dlatego jeśli planujesz dodawanie obrazów do artykułu, musisz użyć programu Visual Studio Code, aby najpierw dodać obrazy do folderu "images" rozwidlenia lub upewnić się, że wykonano następujące czynności w przeglądarce internetowej:

  1. Rozwidlenie repozytorium MicrosoftDocs/hololens.
  2. Edytowano artykuł w rozwidleniu.
  3. Przekazano obrazy, do których odwołujesz się w artykule, do folderu "hololens/images" w rozwidleniu.
  4. Utworzono żądanie ściągnięcia , aby scalić rozwidlenie z gałęzią main MicrosoftDocs/hololens.

Aby dowiedzieć się, jak skonfigurować własne rozwidlenie repozytorium, postępuj zgodnie z instrukcjami dotyczącymi tworzenia nowego artykułu.

Wyświetlanie podglądu pracy

Podczas edytowania w usłudze GitHub za pośrednictwem przeglądarki internetowej możesz wybrać kartę Preview w górnej części strony, aby wyświetlić podgląd pracy przed zatwierdzeniem.

Uwaga

Podgląd zmian w witrynie Microsoft Learn jest dostępny tylko dla pracowników firmy Microsoft.

Pracownicy firmy Microsoft: Po scaleniu kontrybucji z gałęzią domyślną głównymmożesz przejrzeć zawartość, zanim przejdzie ona publicznie w </hololens?branch=main>. Znajdź artykuł przy użyciu spisu treści w lewej kolumnie.

Edytowanie w przeglądarce a edytowanie przy użyciu klienta klasycznego

Edytowanie w przeglądarce jest najprostszym sposobem wprowadzania szybkich zmian, jednak istnieje kilka wad:

  • Nie uzyskujesz sprawdzania pisowni.
  • Nie uzyskujesz żadnego inteligentnego łączenia z innymi artykułami (musisz ręcznie wpisać nazwę pliku artykułu).
  • Przekazywanie i odwoływanie się do obrazów może być kłopotliwe.

Jeśli nie chcesz radzić sobie z tymi problemami, użyj klienta klasycznego, takiego jak Visual Studio Code z kilkoma przydatnymi rozszerzeniami podczas współtworzenia.

Korzystanie z programu Visual Studio Code

Ze względów wymienionych powyżejmożesz użyć klienta klasycznego do edytowania dokumentacji zamiast przeglądarki internetowej. Zalecamy używanie programu Visual Studio Code.

Instalacji

Wykonaj następujące kroki, aby skonfigurować program Visual Studio Code do pracy z tym repozytorium:

  1. W przeglądarce internetowej:
    1. Zainstaluj Git dla komputera.
    2. Zainstaluj programu Visual Studio Code.
    3. Fork MicrosoftDocs/hololens, jeśli jeszcze tego nie zrobiono.
    4. W rozwidleniu wybierz pozycję Klonuj lub pobierz i skopiuj adres URL.
  2. Utwórz lokalny klon rozwidlenia w programie Visual Studio Code:
    1. Z menu Widok wybierz pozycję Paleta poleceń.
    2. Wpisz "Git: Clone".
    3. Wklej skopiowany adres URL.
    4. Wybierz miejsce zapisania klonu na komputerze.
    5. Wybierz pozycję Otwórz repozytorium w oknie podręcznym.

Edytowanie dokumentacji

Użyj następującego przepływu pracy, aby wprowadzić zmiany w dokumentacji za pomocą programu Visual Studio Code:

Uwaga

Wszystkie wskazówki dotyczące edytowania i tworzenia artykułów oraz podstawy edytowaniaJęzyka Markdown z powyższego mają zastosowanie również podczas korzystania z programu Visual Studio Code.

  1. Upewnij się, że sklonowany rozwidlenie jest aktualne w oficjalnym repozytorium.

    1. W przeglądarce internetowej utwórz żądanie ściągnięcia, aby zsynchronizować ostatnie zmiany z innych współautorów w domyślnej gałęzi MicrosoftDocs/hololens, głównym, do rozwidlenia (upewnij się, że strzałka wskazuje na poprawne miejsce docelowe).

      Zmiany synchronizacji z microsoftDocs/hololens na rozwidlenie.

    2. W programie Visual Studio Code wybierz przycisk synchronizacji, aby zsynchronizować świeżo zaktualizowane rozwidlenie z klonem lokalnym.

      kliknij obraz przycisku synchronizacji.

  2. Tworzenie lub edytowanie artykułów w sklonowanym repozytorium przy użyciu programu Visual Studio Code.

    1. Edytuj co najmniej jeden artykuł (w razie potrzeby dodaj obrazy do folderu "images").

    2. Zapisz zmiany w programie Explorer.

      wybierz pozycję

    3. Zatwierdź wszystkie zmiany w kontroli kodu źródłowego (po wyświetleniu monitu komunikat o zatwierdzeniu zapisu).

      wybierz pozycję kontroli kodu źródłowego

    4. Wybierz przycisk synchronizacji , aby zsynchronizować zmiany z powrotem ze źródłem (rozwidlenie w usłudze GitHub).

      kliknij przycisk synchronizacji.

  3. W przeglądarce internetowej utwórz żądanie ściągnięcia, aby zsynchronizować nowe zmiany w rozwidleniu z powrotem do dokumentów MicrosoftDocs/hololens głównym (upewnij się, że strzałka wskazuje prawidłową lokalizację docelową).

    Utwórz żądanie ściągnięcia z rozwidlenia do dokumentów MicrosoftDocs/hololens.

Przydatne rozszerzenia

Podczas edytowania dokumentacji przydatne są następujące rozszerzenia programu Visual Studio Code:

  • Rozszerzenia języka Markdown witryny Docs dla programu Visual Studio Code — użyj Alt+M, aby wyświetlić menu opcji tworzenia w witrynie Microsoft Learn, takich jak:

    • Przeszukaj przekazane obrazy i odwoływanie się do tych obrazów.
    • Dodaj formatowanie, takie jak listy, tabele i objaśnienie, takie jak >[!NOTE].
    • Wyszukaj i odwołuj się do wewnętrznych linków i zakładek (linki do określonych sekcji na stronie).
    • Błędy formatowania są wyróżnione (umieść wskaźnik myszy na błędzie, aby dowiedzieć się więcej).
  • code spell checker — błędnie napisane wyrazy zostaną podkreślone; Kliknij prawym przyciskiem myszy błędnie napisany wyraz, aby go zmienić lub zapisać w słowniku.