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!
Nazwa repozytorium | Adres URL |
---|---|
HoloLens | MicrosoftDocs/HoloLens |
Rzeczywistość mieszana | MicrosoftDocs/mixed-reality |
Przewodnik entuzjastów VR | MicrosoftDocs/mixed-reality/entuzjasty-guide |
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
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.
Użyj następującego przepływu pracy, aby zaktualizować istniejącego artykułu za pośrednictwem usługi GitHub w przeglądarce internetowej:
Przejdź do artykułu, który chcesz edytować w folderze "hololens".
Wybierz przycisk edycji (ikona ołówka) w prawym górnym rogu.
Spowoduje to automatyczne rozwidlenie jednorazowej gałęzi z gałęzi domyślnej, main.
Edytuj zawartość artykułu zgodnie z Podstawy języka Markdown.
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.
Po zakończeniu edycji artykułu przewiń w dół i wybierz pozycję Zaproponuj zmianę pliku.
Na następnej stronie wybierz pozycję Utwórz żądanie ściągnięcia, aby scalić automatycznie utworzoną gałąź z gałęzią domyślną main.
Powtórz powyższe kroki dla następnego artykułu, który chcesz edytować.
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 przypadkuhololens
) 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 tofalse
. Użyjtrue
, jeśli chcesz zachować wartość atrybutums.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.
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:
Utwórz rozwidlenie od gałęzi domyślnej, main, microsoftDocs/hololens przy użyciu przycisku rozwidlenia w prawym górnym rogu.
W folderze "hololens" wybierz pozycję Utwórz nowy plik w prawym górnym rogu.
Utwórz nazwę strony artykułu (użyj łączników zamiast spacji i nie używaj interpunkcji ani apostrofów) i dołącz ".md"
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.
W górnej części nowej strony dodaj następujący blok metadanych:
--- title: description: author: ms.author: ms.date: ms.topic: article keywords: ---
Wypełnij odpowiednie pola metadanych zgodnie z opisem we wcześniejszej sekcji Edytowanie istniejącego artykułu.
Pisanie zawartości artykułu przy użyciu podstaw języka Markdown.
Dodaj sekcję
## See also
w dolnej części artykułu z linkami do innych odpowiednich artykułów.Po zakończeniu wybierz pozycję Zatwierdź nowy plik.
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ą).
Następujące zasoby pomogą Ci dowiedzieć się, jak edytować dokumentację przy użyciu języka Markdown:
- podstawy języka Markdown
- [Dodatkowe zasoby do pisania języka Markdown dla
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.
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:
- Rozwidlenie repozytorium MicrosoftDocs/hololens.
- Edytowano artykuł w rozwidleniu.
- Przekazano obrazy, do których odwołujesz się w artykule, do folderu "hololens/images" w rozwidleniu.
- 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.
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 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.
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.
Wykonaj następujące kroki, aby skonfigurować program Visual Studio Code do pracy z tym repozytorium:
- W przeglądarce internetowej:
- Zainstaluj Git dla komputera.
- Zainstaluj programu Visual Studio Code.
- Fork MicrosoftDocs/hololens, jeśli jeszcze tego nie zrobiono.
- W rozwidleniu wybierz pozycję Klonuj lub pobierz i skopiuj adres URL.
- Utwórz lokalny klon rozwidlenia w programie Visual Studio Code:
- Z menu Widok
wybierz pozycję Paleta poleceń . - Wpisz "Git: Clone".
- Wklej skopiowany adres URL.
- Wybierz miejsce zapisania klonu na komputerze.
- Wybierz pozycję Otwórz repozytorium w oknie podręcznym.
- Z menu Widok
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.
Upewnij się, że sklonowany rozwidlenie jest aktualne w oficjalnym repozytorium.
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).
W programie Visual Studio Code wybierz przycisk synchronizacji, aby zsynchronizować świeżo zaktualizowane rozwidlenie z klonem lokalnym.
Tworzenie lub edytowanie artykułów w sklonowanym repozytorium przy użyciu programu Visual Studio Code.
Edytuj co najmniej jeden artykuł (w razie potrzeby dodaj obrazy do folderu "images").
Zapisz zmiany w programie Explorer.
Zatwierdź wszystkie zmiany w kontroli kodu źródłowego(po wyświetleniu monitu komunikat o zatwierdzeniu zapisu). kontroli kodu źródłowego
Wybierz przycisk synchronizacji , aby zsynchronizować zmiany z powrotem ze źródłem (rozwidlenie w usłudze GitHub).
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ą).
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.