From 8c23def1927a0db3542d2f1bde4cd159f60c5bbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20M=C3=AD=C5=A1ek?= Date: Sun, 25 Aug 2024 22:35:34 +0200 Subject: [PATCH] docs & mkdocs material --- .gitignore | 3 +- docs/.pages | 4 - docs/.vscode/launch.json | 14 ++ docs/{ => content}/add-plugin-theme.md | 4 +- docs/{ => content}/aspnetcore-wordpress.md | 2 +- docs/{ => content}/build-php-plugin.md | 4 +- docs/{ => content}/build-php-theme.md | 4 +- docs/{ => content}/configuration.md | 0 docs/{ => content}/img/appsettings.png | Bin ...e-nuget-peachpied-wordpress-aspnetcore.png | Bin docs/{ => content}/img/mysql-in-app.png | Bin .../img/new-aspnetcore-csharp.png | Bin .../img/new-aspnetcore-step2.png | Bin docs/{ => content}/img/publish.png | Bin docs/{ => content}/img/startup-class.png | Bin docs/{ => content}/img/vs-gallery.png | Bin docs/{ => content}/img/watermark.png | Bin .../{ => content}/img/wp-dashboard-glance.png | Bin docs/{overview.md => content/index.md} | 13 +- docs/content/patreon.md | 4 + docs/mkdocs.yml | 164 ++++++++++++++++++ docs/setup.cmd | 2 + 22 files changed, 203 insertions(+), 15 deletions(-) delete mode 100644 docs/.pages create mode 100644 docs/.vscode/launch.json rename docs/{ => content}/add-plugin-theme.md (96%) rename docs/{ => content}/aspnetcore-wordpress.md (99%) rename docs/{ => content}/build-php-plugin.md (94%) rename docs/{ => content}/build-php-theme.md (93%) rename docs/{ => content}/configuration.md (100%) rename docs/{ => content}/img/appsettings.png (100%) rename docs/{ => content}/img/browse-nuget-peachpied-wordpress-aspnetcore.png (100%) rename docs/{ => content}/img/mysql-in-app.png (100%) rename docs/{ => content}/img/new-aspnetcore-csharp.png (100%) rename docs/{ => content}/img/new-aspnetcore-step2.png (100%) rename docs/{ => content}/img/publish.png (100%) rename docs/{ => content}/img/startup-class.png (100%) rename docs/{ => content}/img/vs-gallery.png (100%) rename docs/{ => content}/img/watermark.png (100%) rename docs/{ => content}/img/wp-dashboard-glance.png (100%) rename docs/{overview.md => content/index.md} (91%) create mode 100644 docs/content/patreon.md create mode 100644 docs/mkdocs.yml create mode 100644 docs/setup.cmd diff --git a/.gitignore b/.gitignore index b2d905d45..fdfbce53b 100644 --- a/.gitignore +++ b/.gitignore @@ -256,4 +256,5 @@ paket-files/ wordpress/wp-content/plugins/akismet wordpress/wp-content/plugins/hello.php wordpress/wp-content/themes/twentysixteen -wordpress/wp-content/uploads/ \ No newline at end of file +wordpress/wp-content/uploads/ +docs/site diff --git a/docs/.pages b/docs/.pages deleted file mode 100644 index aca414d2e..000000000 --- a/docs/.pages +++ /dev/null @@ -1,4 +0,0 @@ -title: WordPress -arrange: - - overview.md - - configuration.md diff --git a/docs/.vscode/launch.json b/docs/.vscode/launch.json new file mode 100644 index 000000000..227b70986 --- /dev/null +++ b/docs/.vscode/launch.json @@ -0,0 +1,14 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "serve", + "request": "launch", + "type": "node-terminal", + "command": "mkdocs serve" + } + ] +} \ No newline at end of file diff --git a/docs/add-plugin-theme.md b/docs/content/add-plugin-theme.md similarity index 96% rename from docs/add-plugin-theme.md rename to docs/content/add-plugin-theme.md index 972132288..bf56ae8d7 100644 --- a/docs/add-plugin-theme.md +++ b/docs/content/add-plugin-theme.md @@ -40,5 +40,5 @@ Using **Visual Studio**, right click on your project and click command `Manage N Package is created from regular PHP WordPress plugin or theme. Refer to following instructions on how to create a .NET project and eventually a NuGet package from sources: -- [Build a plugin](../build-php-plugin/) -- [Build a theme](../build-php-theme/) +- [Build a plugin](build-php-plugin.md) +- [Build a theme](build-php-theme.md) diff --git a/docs/aspnetcore-wordpress.md b/docs/content/aspnetcore-wordpress.md similarity index 99% rename from docs/aspnetcore-wordpress.md rename to docs/content/aspnetcore-wordpress.md index c771f6b82..53b33e201 100644 --- a/docs/aspnetcore-wordpress.md +++ b/docs/content/aspnetcore-wordpress.md @@ -41,7 +41,7 @@ The following tutorial is shown in Visual Studio 2019. ``` - The optional `services.AddWordPress( ... )` can be used to alter the WordPress configuration, such as the Site URL, database connection credentials and others, as described in [configuration](../configuration/). + The optional `services.AddWordPress( ... )` can be used to alter the WordPress configuration, such as the Site URL, database connection credentials and others, as described in [configuration](configuration.md). 5. Prepare the MySQL server. Make sure you have MySQL server running: diff --git a/docs/build-php-plugin.md b/docs/content/build-php-plugin.md similarity index 94% rename from docs/build-php-plugin.md rename to docs/content/build-php-plugin.md index 7078789aa..df24bace3 100644 --- a/docs/build-php-plugin.md +++ b/docs/content/build-php-plugin.md @@ -6,7 +6,7 @@ By default, plugins are compiled automatically just by copying them into the Wor - you need to have source code of the plugin on the server (security). - eventual code errors are revealed upon starting the application (reliability). -In order to avoid those issues, plugins can be pre-compiled during the deployment process. A single WordPress plugin or the `plugins` directory is then defined as a PHP class library project (below) which is then referenced by the application (see [overview](overview)). Application can have references to one or more plugin projects. +In order to avoid those issues, plugins can be pre-compiled during the deployment process. A single WordPress plugin or the `plugins` directory is then defined as a PHP class library project (below) which is then referenced by the application (see [overview](index.md)). Application can have references to one or more plugin projects. **Sample project**: https://github.com/iolevel/peachpie-wordpress/tree/master/MyContent @@ -76,7 +76,7 @@ The process will build the plugin project. Eventual warnings will be outputed. A ### Add plugin to the application -Assuming you have ASP.NET Core Application (called *app*) with WordPress (see [quick start](../overview/#quick-start)). Adding plugins to the application is equivalent to adding project references or package references. +Assuming you have ASP.NET Core Application (called *app*) with WordPress (see [quick start](index.md#quick-start)). Adding plugins to the application is equivalent to adding project references or package references. Either add project reference to the plugin in Visual Studio IDE, or on command line, or edit the application's project file: diff --git a/docs/build-php-theme.md b/docs/content/build-php-theme.md similarity index 93% rename from docs/build-php-theme.md rename to docs/content/build-php-theme.md index ca9148225..4a0fd9ec2 100644 --- a/docs/build-php-theme.md +++ b/docs/content/build-php-theme.md @@ -1,6 +1,6 @@ # Build a PHP theme -Please see [Build a Plugin](build-php-plugin) for more details. +Please see [Build a Plugin](build-php-plugin.md) for more details. Single theme for WordPress or the whole `themes` directory is defined as a PHP class library project (below) which is then referenced by the application. Application can have references to one or more themes. @@ -52,7 +52,7 @@ The process will build the theme project. Eventual warnings will be outputed. An ### Add theme to the application -Assuming you have ASP.NET Core Application (called *app*) with WordPress (see [quick start](../overview/#quick-start)). Adding themes to the application is equivalent to adding project references or package references. +Assuming you have ASP.NET Core Application (called *app*) with WordPress (see [quick start](index.md#quick-start)). Adding themes to the application is equivalent to adding project references or package references. Either add project reference to the theme in Visual Studio IDE, or on command line, or edit the application's project file: diff --git a/docs/configuration.md b/docs/content/configuration.md similarity index 100% rename from docs/configuration.md rename to docs/content/configuration.md diff --git a/docs/img/appsettings.png b/docs/content/img/appsettings.png similarity index 100% rename from docs/img/appsettings.png rename to docs/content/img/appsettings.png diff --git a/docs/img/browse-nuget-peachpied-wordpress-aspnetcore.png b/docs/content/img/browse-nuget-peachpied-wordpress-aspnetcore.png similarity index 100% rename from docs/img/browse-nuget-peachpied-wordpress-aspnetcore.png rename to docs/content/img/browse-nuget-peachpied-wordpress-aspnetcore.png diff --git a/docs/img/mysql-in-app.png b/docs/content/img/mysql-in-app.png similarity index 100% rename from docs/img/mysql-in-app.png rename to docs/content/img/mysql-in-app.png diff --git a/docs/img/new-aspnetcore-csharp.png b/docs/content/img/new-aspnetcore-csharp.png similarity index 100% rename from docs/img/new-aspnetcore-csharp.png rename to docs/content/img/new-aspnetcore-csharp.png diff --git a/docs/img/new-aspnetcore-step2.png b/docs/content/img/new-aspnetcore-step2.png similarity index 100% rename from docs/img/new-aspnetcore-step2.png rename to docs/content/img/new-aspnetcore-step2.png diff --git a/docs/img/publish.png b/docs/content/img/publish.png similarity index 100% rename from docs/img/publish.png rename to docs/content/img/publish.png diff --git a/docs/img/startup-class.png b/docs/content/img/startup-class.png similarity index 100% rename from docs/img/startup-class.png rename to docs/content/img/startup-class.png diff --git a/docs/img/vs-gallery.png b/docs/content/img/vs-gallery.png similarity index 100% rename from docs/img/vs-gallery.png rename to docs/content/img/vs-gallery.png diff --git a/docs/img/watermark.png b/docs/content/img/watermark.png similarity index 100% rename from docs/img/watermark.png rename to docs/content/img/watermark.png diff --git a/docs/img/wp-dashboard-glance.png b/docs/content/img/wp-dashboard-glance.png similarity index 100% rename from docs/img/wp-dashboard-glance.png rename to docs/content/img/wp-dashboard-glance.png diff --git a/docs/overview.md b/docs/content/index.md similarity index 91% rename from docs/overview.md rename to docs/content/index.md index b419d3fca..4663c31ca 100644 --- a/docs/overview.md +++ b/docs/content/index.md @@ -1,3 +1,10 @@ +--- +title: Overview +social: + cards_layout_options: + title: Documentation that simply works +--- + # Overview [WpDotNet](https://wpdotnet.peachpie.io/) is the unmodified WordPress, running compiled purely on .NET, provided as a NuGet package & ready to be used as a part of an ASP NET Core application. WpDotNet comes with additional components and features, making it easy to be used from C# and a .NET development environment in general. @@ -6,7 +13,7 @@ The project does not require PHP to be installed, and is purely built on top of ## Requirements -- .NET CoreSDK 3.0, .NET SDK 5.0, or newer. ([dotnet.microsoft.com](https://dotnet.microsoft.com/download) or [visualstudio.microsoft.com](https://visualstudio.microsoft.com/vs/)) +- .NET SDK 6.0, or newer. ([dotnet.microsoft.com](https://dotnet.microsoft.com/download) or [visualstudio.microsoft.com](https://visualstudio.microsoft.com/vs/)) - MySQL Server ([dev.mysql.com](https://dev.mysql.com/downloads/mysql/) or [docker](https://hub.docker.com/_/mysql)) Make sure you have valid credentials to your MySQL server and you have created a database in it. The following quick start expects a database named `"wordpress"`. Database charset `"UTF-8"` is recommended. @@ -20,7 +27,7 @@ Open or create an ASP NET Core application, version 3.0 or newer. Add a package reference to [`"Peachpied.WordPress.AspNetCore"`](https://www.nuget.org/packages/PeachPied.WordPress.AspNetCore/) (note it is a **pre-release** package): ```shell -dotnet add package PeachPied.WordPress.AspNetCore --version 6.3.1-rc-016 +dotnet add package PeachPied.WordPress.AspNetCore --version 6.5.4-rc-020 ``` Add the WordPress middleware within your request pipeline, in the `Configure` startup method: @@ -54,7 +61,7 @@ public partial class Startup } ``` -> Note: the recommended approach is to place the configuration within the `appsettings.json` configuration file. See [configuration](../configuration) for more details. +> Note: the recommended approach is to place the configuration within the `appsettings.json` configuration file. See [configuration](configuration.md) for more details. ## Dashboard diff --git a/docs/content/patreon.md b/docs/content/patreon.md new file mode 100644 index 000000000..466ba76b6 --- /dev/null +++ b/docs/content/patreon.md @@ -0,0 +1,4 @@ +--- +title: Patreon +--- + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 000000000..0bcb6d6b3 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,164 @@ +# Project information +site_name: WpDotNet - WordPress on .NET +site_url: https://www.wpdotnet.com/ +site_author: PeachPie Team +site_description: >- + This site provides WpDotNet project documentation and useful tips. + +# Repository +repo_name: iolevel/wpdotnet +repo_url: https://github.com/iolevel/wpdotnet + +# Copyright +copyright: Copyright © iolevel s.r.o. All rights reserved. + +# Configuration +theme: + name: material + features: + - announce.dismiss + #- content.action.edit + #- content.action.view + - content.code.annotate + - content.code.copy + - content.code.select + # - content.footnote.tooltips + # - content.tabs.link + - content.tooltips + # - header.autohide + # - navigation.expand + - navigation.footer + - navigation.indexes + # - navigation.instant + # - navigation.instant.prefetch + # - navigation.instant.progress + # - navigation.prune + - navigation.sections + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + # - toc.integrate + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/link + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/toggle-switch + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: indigo + toggle: + icon: material/toggle-switch-off + name: Switch to system preference + font: + text: Roboto + code: Roboto Mono + favicon: assets/favicon.png + icon: + logo: logo + +# Plugins +plugins: + # - blog + # - search: + # separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])' + - minify: + minify_html: true + +# Hooks +# hooks: +# - material/overrides/hooks/shortcodes.py +# - material/overrides/hooks/translations.py + +# Additional configuration +extra: + status: + new: Recently added + deprecated: Deprecated + analytics: + provider: google + property: !ENV GOOGLE_ANALYTICS_KEY + generator: false + social: + - icon: fontawesome/brands/github + link: https://github.com/peachpiecompiler + - icon: fontawesome/brands/x-twitter + link: https://x.com/pchpcompiler + - icon: fontawesome/brands/facebook + link: https://facebook.com/pchpcompiler + - icon: fontawesome/brands/youtube + link: https://youtube.com/@PEACHPIE + - icon: fontawesome/brands/discord + link: https://discord.com/channels/1198334116182102177/1198334116182102180 + + + +# Extensions +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + normalize_issue_symbols: true + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.snippets: + auto_append: + - includes/mkdocs.md + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + combine_header_slug: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +# Page tree + +docs_dir: content + +# nav: +# - Home: 'index.md' +# - Patreon: 'patreon.md' \ No newline at end of file diff --git a/docs/setup.cmd b/docs/setup.cmd new file mode 100644 index 000000000..7b54e58e3 --- /dev/null +++ b/docs/setup.cmd @@ -0,0 +1,2 @@ +pip install mkdocs mkdocs-material mkdocs-minify-plugin +mkdocs build