Open Source Project Structure

Do as the Romans do

Most open source projects follow common pattern for directory structure which looks somewhat like this:


This makes sense and easy to understand - you put your source files under src, distribution files go to dist, unit tests under tests. If you have a build utility it goes under build, samples take their own place and so on. Nothing wrong with that, so I mostly follow it for Blogifier and ended up with this structure:


docs has documentation in markdown format. I decided against using Github's wiki, because documentation is version specific and keeping it in the wiki would require maintain all the version differences. This way, you pull docs along with source code and, at least in theory, they match.

plugins would have any extensions to the core functionality, like custom themes and widgets. The common project has all the common plugins, to build new developer would add another project here. Resulted DLL could be side-loaded at run time, so down the road it could be pulled from common store or repository.

src has two projects. One is app which is web application or blog itself. It is ASP.NET Core application utilizing MVC for the blog features and Razor Pages for admin panel. Distinction is because MVC ideal for manipulating blog routes and plug in on the fly themes and widgets. Razor Pages are great in separating application by features so it can be structured really nicely. Second project here is core - class library with core back-end functionality (services, data access etc.).

tests currently has unit tests mostly covering logic in services. If there need for example to have integration testing, the app.tests project can be added here. Same goes for plugins - you write your plugin - you can add tests for it here, in plugin-name.tests project.

Solution Folders

Visual Studio has a feature called solution folders - whenever you add new project to solution it is added as virtual folder, no physical folder actually added to the file system. At least not where you would expect it. This can be very misleading and, when you switch to file-based editor, like VS Code or Atom, your projects look messed up. To avoid this, I always create physical folder and select it for new project so that virtual and physical match.

Deep nesting

Not a fan of deep nesting, that's why tests and plugins at top level instead of nesting under src. Just a personal preference.


I started by creating wiki pages in Github, but quickly realized this is going to be hard to keep up with changes in every version. So instead of having this only applies for version 1.2.3 statements, all documentation is going into docs folder and naturally version specific. Just as it is all in markdown format.

Hope this makes sense and easy to follow, if you have better ideas comments are welcome.


This site is all about developing web applications with focus on designing and building open source blogging solutions. Technologies include ASP.NET Core, C#, Angular, JavaScript and more.