This is this repository for MoreLINQ documentation.
Documentation is written in Markdown format and built using MkDocs and MarkdownSnippets.
The following software is required for building:
- .NET Core SDK 2.2 or later
- Docker
Other required tools can be installed by running install.cmd on Windows or
install.sh on Linux/macOS.
Make sure that the project root is the current working directory of your command-line shell.
Then if on Windows, run:
dotnet build && ^
docker run --rm -it ^
-v "%cd%:/docs" ^
--entrypoint /bin/sh ^
squidfunk/mkdocs-material -c "mkdocs build"
If on Linux or macOS, run instead:
dotnet build && \
docker run --rm -it \
-v "$(pwd):/docs" \
--entrypoint /bin/sh \
squidfunk/mkdocs-material -c "mkdocs build"
The resulting web site can be found in the site directory.
When writing documentation, it is helpful to preview it locally in a browser and refresh automatically as each document is saved. To do so, open two command-line shell terminals and change the current working directory of both to the project root. Then run the following in one of the terminals:
dotnet watch build
In the second terminal and if on Windows, run:
docker run --rm -it -v -p 8000:8000 ^
"%cd%:/docs" squidfunk/mkdocs-material
Otherwise run the following if on Linux or macOS:
docker run --rm -it -v -p 8000:8000 \
"$(pwd):/docs" squidfunk/mkdocs-material
Next, open a Web browser and navigate to http://localhost:8000/.
Note that due to a bug in dotnet watch, new C# source files or Markdown
documents are not detected so after creating such a file, touch the
doc.proj file or force-save in the editor. There are also known issues with
Docker containers failing to sometimes pick up on file notifications on Windows.
If that seems the case then touching or force-saving the mkdocs.yml file
usually fixes the situation.