diff --git a/docs/dev-corner/development-projects/.pages b/docs/dev-corner/development-projects/.pages index 08fffc77c..a8e4a92be 100644 --- a/docs/dev-corner/development-projects/.pages +++ b/docs/dev-corner/development-projects/.pages @@ -1,7 +1,7 @@ title: FlyByWire Projects nav: - Overview: index.md - - Documentation Project: documentation.md + - Documentation Project: documentation-project - Website Project: website.md - Discord Bot: discord-bot.md - Advanced Cockpit Emulator: ace.md diff --git a/docs/dev-corner/development-projects/documentation-project/.pages b/docs/dev-corner/development-projects/documentation-project/.pages new file mode 100644 index 000000000..cbf68a26e --- /dev/null +++ b/docs/dev-corner/development-projects/documentation-project/.pages @@ -0,0 +1,3 @@ +nav: + - Development Environment: documentation.md + - ... diff --git a/docs/dev-corner/development-projects/documentation.md b/docs/dev-corner/development-projects/documentation-project/documentation.md similarity index 61% rename from docs/dev-corner/development-projects/documentation.md rename to docs/dev-corner/development-projects/documentation-project/documentation.md index a007c9cda..9269e370d 100644 --- a/docs/dev-corner/development-projects/documentation.md +++ b/docs/dev-corner/development-projects/documentation-project/documentation.md @@ -4,6 +4,11 @@ ## Background +!!! info "Guides" + If you would like to setup the documentation project locally please continue with this guide. + + If you would like to understand our guidelines on writing and different available features please see the [Writing Documentation](writing-documentation.md) Page instead. + The FlyByWire Documentation Project aims to provide all necessary information and documentation to successfully install and use the FlyByWire A32NX aircraft in Microsoft Flight Simulator. For this, we provide documentation about the A32NX add-on itself, but also valuable additional documentation on how to fly an airliner on Microsoft Flight Simulator in general and even some specific A320neo documentation for the more involved user. @@ -116,7 +121,7 @@ feature. 1. For production or PR purposes, please ensure that the above plugin reads `external-markdown: {}` (without the preceding `#`) before finalizing your PR. !!! info "Faster Preview Server" - You can opt to use a faster instance of the developer server by invoking the flag `--dirtyreload`. This just checks for any markdown that has changed since the HTML was rendered and will reconstruct any relevant pages only, rather than rebuilding the entire website. + You can opt to use a faster instance of the developer server by invoking the flag `--dirty`. This just checks for any markdown that has changed since the HTML was rendered and will reconstruct any relevant pages only, rather than rebuilding the entire website. ``` mkdocs.exe serve --dirty @@ -184,106 +189,6 @@ If you would like to fully test a complete build of the production website, you - Social Cards -### How to Write Documentation for FlyByWire - -#### Technical How-To - -- You can edit existing pages simply by editing an existing `pagename.md`. -- To create a page, simply create a new file "pagename.md" in an appropriate folder and start writing your documentation. Best practices it to look at other pages regarding the general structure (Headings, Material for MkDocs features, etc.). -- Create the page in the navigation folder you feel this page belongs to. The Documentation Team will be happy to support you with the best location and also how to create a navigation to your page. -- During the PR Review, the page can still be moved and navigation can be changed/added. So don't worry too much about it and focus on the content for your page. -- Add images to the section's asset folder. Consider creating a folder for your page when using several images. -- Although the FlyByWire Documentation Team will take care of navigation, it might still be of interest how the navigation is done. This is well explained on the [mkdocs-awesome-pages-plugin's README on their GitHub](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin#Features){target=new} - -!!! tip "Embedding YouTube Videos" - We have included the plugin `mkdocs-video` to streamline adding YouTube embeds into documentation. This removes the necessity to inline `