Z-Blog

This is the second iteration of my personal portfolio + blog using Blazor WebAssembly.

The code in this repository is not meant to be a theme template nor cloned or deployed, its for my own personal use, if it helps you, feel free to take whatever inspiration you want from it.

The Idea

As part of my process to learn Blazor Web Assembly, i will be creating a static blog that takes posts as markdown files with yaml metadata and output .html + .yml files for every post and display them dynamically.

Project Structure

The solution consists of two projects:

HMZ-Software

The main blazor wasm app, it contains all the logic and components to form the website.

Blog

The blog is located in wwwroot and structured like this:

• Blog
  • Metadata
  • Posts
  • Site

The Metadata directory has a Metadata.json file that contains all the posts' metadata which is constructed by the MarkdownCompiler project. The purpose of the Metadata.json file is to bypass the limitation of enumerating over files in wwwroot, it contains all the user provided posts' metadata: Title, Dates, Tags, etc.

The Posts directory contains the markdown files that'll be compiled to .html and .yml on build via the MarkdownCompiler project.

The Site directory contains the compilation output of the MarkdownCompiler project .html and .yml files for every post.

Logic and Services

• The IBlogPostProcessorService handles processing of html, yaml and json files.
• The ProcessPostAsync and ProcessPostMetadataAsync processes posts and metadata files respectively.
• The ProcessPostsMetadataAsync fetches the Metadata.json file and caches it in a global static variable named GlobalVariables.YamlMetadata.

Pages

• The Blog page has the BlogPosts components which renders all the posts by injecting the IBlogPostProcessorService service and fetching the Metadata.json file by calling ProcessPostsMetadataAsync.
• The Post page renders a specific post by injecting IBlogPostProcessorService service and fetching the post related files by calling ProcessPostAsync. The files are deserialized to a BlogPostDocument type which has a Markdown, html and Yaml properties.

Components

• The BlogPost component renders the blog post cards in the Blog page.
• The ProjectCards component renders my GitHub repositories as cards using the GitHub API and it calls the Intersection Observer on initialization using the IJSRuntime in order to call the API once the component is in the viewport and it caches the received data in the static global variable GlobalVariables.GitHubData.

MarkdownCompiler

• The MarkdownCompiler is the project responsible for compiling the markdown files.
• The project is triggered to run on every build as a Visual Studio post build event.

What does it do?

1. Performs clean up on the Blog directory (if it exists) to clear it from old posts and metadata files so it can start compiling the files again.
2. Create the blog structure in the main project if it's not created.
3. Parse markdown files that also consists of yaml markup, separate them into compiled html and yml files and write them to the Site directory.
4. Construct the Metadata.json file that represents the posts' metadata.
5. Any exceptions are logged to ExecuteLog.log in the assembly directory.

Robots.txt and Sitemap.xml

• Robots.txt and Sitemap.xml are generated automatically with the MarkdownCompiler via the Seo class.
• The process checks for a NoList property on posts' metadata in order to decide if it should be added to Robots.txt or not.
• Sitemap.xml is generated using the same json metadata via the XmlDocument class.
• Static pages are hardcoded in both files.

Libraries Used

• Markdig for markdown compilation.
• YamlDotNet for yaml related operations.
• jQuery.
• PrismJs for syntax highlighting.
• Line Awesome icon font.
• Brotli for blazor file decompression.

Additionally the project uses SASS.

License

Licensed under the GNU General Public License v3.0.

Author

Hamzi Alsheikh

Website: https://www.hamzialsheikh.tk