diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..edd4cb54 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,61 @@ +name: docs + +on: + push: + branches: [ master ] + paths: + - "docs/**" + - "assets/**" + - "MIGRATION.md" + - "docfx.json" + - "dotnet-tools.json" + - ".github/workflows/docs.yml" + pull_request: + branches: [ master ] + paths: + - "docs/**" + - "assets/**" + - "MIGRATION.md" + - "docfx.json" + - "dotnet-tools.json" + - ".github/workflows/docs.yml" + workflow_dispatch: + +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - name: Setup .NET + uses: actions/setup-dotnet@v6 + with: + dotnet-version: | + 10.0.x + - name: Restore tools + run: dotnet tool restore + - name: Build documentation + run: dotnet docfx docfx.json --warningsAsErrors + - name: Upload site + if: github.event_name != 'pull_request' + uses: actions/upload-pages-artifact@v5 + with: + path: _site + + deploy: + if: github.event_name != 'pull_request' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index 9be89c32..96d27f56 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,7 @@ backups/ # Local image storage provider uploads src/LinkDotNet.Blog.Web/wwwroot/uploads/ + +# DocFX output +/_site/ +/obj/ diff --git a/Readme.md b/Readme.md index f8a8f4fb..1658038e 100644 --- a/Readme.md +++ b/Readme.md @@ -38,6 +38,8 @@ This also includes source code snippets. Highlighting is done via [highlight.js] ## Documentation +The documentation is published at **[linkdotnet.github.io/Blog](https://linkdotnet.github.io/Blog/)**. The sources live in [`docs`](./docs) and are rendered with [DocFX](https://dotnet.github.io/docfx/). To preview changes locally run `dotnet tool restore` once, followed by `dotnet docfx docfx.json --serve`. + - [Authorization](./docs/Authorization/Readme.md) - [Comments](./docs/Comments/Readme.md) - [Storage Provider](./docs/Storage/Readme.md) diff --git a/docfx.json b/docfx.json new file mode 100644 index 00000000..7eb644f4 --- /dev/null +++ b/docfx.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json", + "build": { + "content": [ + { + "src": "docs", + "files": ["**/*.md", "toc.yml"], + "dest": "." + }, + { + "files": ["MIGRATION.md"] + } + ], + "resource": [ + { + "src": "docs", + "files": ["**/images/**"], + "dest": "." + }, + { + "files": ["assets/overview.gif"] + } + ], + "output": "_site", + "template": ["default", "modern"], + "globalMetadata": { + "_appName": "LinkDotNet.Blog", + "_appTitle": "LinkDotNet.Blog", + "_appFooter": "Released under the MIT License.", + "_enableSearch": true, + "pdf": false + } + } +} diff --git a/docs/Authorization/Auth0.md b/docs/Authorization/Auth0.md index b6748dce..ea7f633e 100644 --- a/docs/Authorization/Auth0.md +++ b/docs/Authorization/Auth0.md @@ -1,4 +1,4 @@ -### Auth0 +# Auth0 Auth0 is a prominent provider of OpenID Connect (OIDC) services, which is an authentication protocol built on top of OAuth 2.0. OpenID Connect is specifically designed for identity layer applications and provides a standardized way for users to authenticate and authorize themselves on websites or applications while allowing third-party applications to access limited user information in a secure manner. diff --git a/docs/Authorization/AzureAD.md b/docs/Authorization/AzureAD.md index 7c0a4b6b..9be043ee 100644 --- a/docs/Authorization/AzureAD.md +++ b/docs/Authorization/AzureAD.md @@ -1,4 +1,4 @@ -### Azure Active Directory +# Azure Active Directory Microsoft Entra ID (old Azure AD) is Microsoft's cloud-based identity and access management service. It supports various identity protocols, including OpenID Connect (OIDC), a standard protocol built on top of OAuth 2.0 for authentication and identity verification. diff --git a/docs/Authorization/Readme.md b/docs/Authorization/Readme.md index 5bf7e0c3..5cd206f8 100644 --- a/docs/Authorization/Readme.md +++ b/docs/Authorization/Readme.md @@ -1,4 +1,4 @@ -### Authentication and Authorization +# Authentication and Authorization When it comes to authentication and authorization, we employ [OpenID Connect](https://openid.net/developers/how-connect-works/) as our preferred method. The primary benefit of an OpenID Connect-based provider is the conveniently customizable dashboard accessible through their website. For the sake of testing, you have the option to employ the `UseDummyAuthentication();` service. This grants every user who clicks "Login" immediate access, effectively logging them in. Here are the platforms we support: diff --git a/docs/Comments/Disqus.md b/docs/Comments/Disqus.md index 2d30d384..ec252d68 100644 --- a/docs/Comments/Disqus.md +++ b/docs/Comments/Disqus.md @@ -1,4 +1,4 @@ -### Disqus +# Disqus For disqus you only need the short name (site-name) which you can find for example under your [home-tab](https://disqus.com/home/). diff --git a/docs/Comments/Giscus.md b/docs/Comments/Giscus.md index d58442d8..02df88e1 100644 --- a/docs/Comments/Giscus.md +++ b/docs/Comments/Giscus.md @@ -1,4 +1,4 @@ -### Giscus +# Giscus To provide the necessary values head over to https://giscus.app/ and go to the configuration section. There you can enter all the information. You will find a detailed guide on the site. diff --git a/docs/Comments/Readme.md b/docs/Comments/Readme.md index 68284106..5690d3e7 100644 --- a/docs/Comments/Readme.md +++ b/docs/Comments/Readme.md @@ -1,4 +1,4 @@ -### Comment Section +# Comment Section Kindly ensure to register just a single service or offer the configuration for a single node. The provided configuration illustrates both elements solely for demonstration purposes. Should multiple comment plugins be set up concurrently, a cautionary message will appear beneath the blog post. diff --git a/docs/Donations/Readme.md b/docs/Donations/Readme.md index ec198592..e170632b 100644 --- a/docs/Donations/Readme.md +++ b/docs/Donations/Readme.md @@ -1,4 +1,4 @@ -## Donations +# Donations The blog software allows you to integrate via different micro-transaction services. The following chapter will show you how to set up donations. diff --git a/docs/Features/AdvancedFeatures.md b/docs/Features/AdvancedFeatures.md index b4cf220b..ad5dd2f6 100644 --- a/docs/Features/AdvancedFeatures.md +++ b/docs/Features/AdvancedFeatures.md @@ -1,4 +1,4 @@ -## Advanced Features +# Advanced Features - [Advanced Features](#advanced-features) - [Shortcodes](#shortcodes) diff --git a/docs/Features/Styling.md b/docs/Features/Styling.md index c0fccc75..edd4c616 100644 --- a/docs/Features/Styling.md +++ b/docs/Features/Styling.md @@ -1,4 +1,4 @@ -## Styling +# Styling - [Styling](#styling) - [Colors \& Fonts](#colors--fonts) diff --git a/docs/Migrations/UpgradeAssistant.md b/docs/Migrations/UpgradeAssistant.md index ed416a88..015428e4 100644 --- a/docs/Migrations/UpgradeAssistant.md +++ b/docs/Migrations/UpgradeAssistant.md @@ -360,7 +360,7 @@ fi - [MIGRATION.md](../../MIGRATION.md) - Complete migration guide with manual steps - [Configuration Documentation](../Setup/Configuration.md) - All configuration options -- [Tool README](../../tools/LinkDotNet.Blog.UpgradeAssistant/README.md) - Developer documentation +- [Tool README](https://github.com/linkdotnet/Blog/blob/master/tools/LinkDotNet.Blog.UpgradeAssistant/README.md) - Developer documentation ## Getting Help diff --git a/docs/SEO/Readme.md b/docs/SEO/Readme.md index 5e522482..0543280c 100644 --- a/docs/SEO/Readme.md +++ b/docs/SEO/Readme.md @@ -1,4 +1,4 @@ -## Search Engine Optimization (SEO) +# Search Engine Optimization (SEO) The blog includes some of the most important tags to get indexed by a crawler. Furthermore, some aspects of the Open Graph specification are implemented. diff --git a/docs/Setup/Configuration.md b/docs/Setup/Configuration.md index 4486c8d3..9dd16e39 100644 --- a/docs/Setup/Configuration.md +++ b/docs/Setup/Configuration.md @@ -1,4 +1,4 @@ -### Configurations +# Configurations ### appsettings.json diff --git a/docs/Setup/Docker.md b/docs/Setup/Docker.md index 968b06d7..f5f26e87 100644 --- a/docs/Setup/Docker.md +++ b/docs/Setup/Docker.md @@ -1,4 +1,4 @@ -## Host the blog in Docker containers +# Host the blog in Docker containers ### Server configuration diff --git a/docs/Setup/Readme.md b/docs/Setup/Readme.md index c89ece7c..b7040b72 100644 --- a/docs/Setup/Readme.md +++ b/docs/Setup/Readme.md @@ -1,4 +1,4 @@ -## Setup +# Setup There are two main ways of using this blog: * Latest development build: Just clone this repository and you are good to go (aka you are using the `master` branch). diff --git a/docs/Storage/Readme.md b/docs/Storage/Readme.md index 1692cdb2..58725806 100644 --- a/docs/Storage/Readme.md +++ b/docs/Storage/Readme.md @@ -1,4 +1,4 @@ -## Storage Provider +# Storage Provider The blog currently supports six storage providers: diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..b3ef8d31 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,31 @@ +# LinkDotNet.Blog + +A blog engine written completely in C# / Blazor, built to be as configurable as possible. + +Authors write posts in markdown, which is rendered to HTML (including syntax-highlighted code snippets) for readers. + +![overview](../assets/overview.gif) + +## Where to start + +- [Setup](Setup/Readme.md) - get the blog running locally or from a release +- [Configuration](Setup/Configuration.md) - all `appsettings.json` options +- [Docker](Setup/Docker.md) - host the blog in containers +- [Upgrading from an older version](Migrations/Readme.md) - breaking changes and the Upgrade Assistant + +## Guides + +- [Storage Provider](Storage/Readme.md) +- [Authorization](Authorization/Readme.md) +- [Comments](Comments/Readme.md) +- [Media Upload](Media/Readme.md) +- [Search Engine Optimization (SEO)](SEO/Readme.md) +- [Donations](Donations/Readme.md) +- [Advanced Features](Features/AdvancedFeatures.md) including [bookmarks, drafts, and scheduled publishing](Features/AdvancedFeatures.md#bookmarks-drafts-and-scheduled-publishing) +- [Styling](Features/Styling.md) + +## Links + +- [Source code](https://github.com/linkdotnet/Blog) +- [Releases](https://github.com/linkdotnet/Blog/releases) +- [Migration guide](../MIGRATION.md) diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 00000000..f47e771f --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,48 @@ +- name: Home + href: index.md +- name: Setup + href: Setup/Readme.md + items: + - name: Configuration + href: Setup/Configuration.md + - name: Docker + href: Setup/Docker.md +- name: Features + items: + - name: Advanced Features + href: Features/AdvancedFeatures.md + - name: Styling + href: Features/Styling.md + - name: Media Upload + href: Media/Readme.md + - name: SEO + href: SEO/Readme.md + - name: Donations + href: Donations/Readme.md +- name: Integrations + items: + - name: Storage Provider + href: Storage/Readme.md + - name: Authorization + href: Authorization/Readme.md + items: + - name: Auth0 + href: Authorization/Auth0.md + - name: Microsoft Entra ID + href: Authorization/AzureAD.md + - name: Comments + href: Comments/Readme.md + items: + - name: Giscus + href: Comments/Giscus.md + - name: Disqus + href: Comments/Disqus.md +- name: Upgrading + href: Migrations/Readme.md + items: + - name: Upgrade Assistant + href: Migrations/UpgradeAssistant.md + - name: Migration Guide + href: ../MIGRATION.md +- name: GitHub + href: https://github.com/linkdotnet/Blog diff --git a/dotnet-tools.json b/dotnet-tools.json new file mode 100644 index 00000000..18264e64 --- /dev/null +++ b/dotnet-tools.json @@ -0,0 +1,13 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "docfx": { + "version": "2.81.0", + "commands": [ + "docfx" + ], + "rollForward": false + } + } +} \ No newline at end of file