Overview

The goal of this workbook is to initialize the FSharp.Formatting document creation utility in one's own repo. The intent is to use FSharp.Formatting to make a blog.

This workbook should be placed in the repo root. FSharp.Formatting may be initialized using the dotnet tool utility.

The standard setup is to have RepoRoot/docs where all your documentation .md and .fsx, etc files go. fsdocs will search through this directory and create the *.html files in the RepoRoot/output directory. There are customizations that can be set using the docs in the FSharp.Formatting repo. If a docs directoy is needed, run:

mkdir docs

::note By making the block a PowerShell, it can be executed right in the notebook.

dotnet tool will error without a "Dotnet local tool manifest file". Create one:

dotnet new tool-manifest

The template "Dotnet local tool manifest file" was created successfully.

The basic command to install Fsharp.Formatting is:

dotnet tool install --local fsdocs-tool

You can invoke the tool from this directory using the following commands: 'dotnet tool run fsdocs' or 'dotnet fsdocs'.
Tool 'fsdocs-tool' (version '20.0.0') was successfully installed. Entry is added to the manifest file /home/linux/CODE/Fxplorer_www/.config/dotnet-tools.json.

fsdocs watch will launch a browser and allow you to browse your created docs. When it launches, it will try to hit index.html and will then 404. One needs to have a index.md or index.fsx file in the docs directy so fsdocs will create the index.html.

Running the build command will search through and generate all the html into an RepoRoot/ output directory.

dotnet fsdocs build

Based on trial and error. The logo is set to /img/logo.png by default. That logo is missing in the inital run. The "input" directory is the docs by default. So fsdocs will convert to html the files in the directory and parady the structure. It will simply copy over anything it finds that is not a file to process (like .fsx,.md,.ipynb, etc.)

Solution File

The recomendation is a solution file in the root folder. Then any projects in the /src directory.

dotnet new sln --name Fxplorer_www

::side note the /src has history on why that is used, so it is basically is historical convention.

:: reference https://garywoodfine.com/what-is-this-directory-build-props-file-all-about/