Modern-CPP-Programming Documentation

1. Project Overview & Quickstart (federico-busato/Modern-CPP-Programming) Copy Chapter

Modern C++ Programming

C++03 / C++11 / C++14 / C++17 / C++20 / C++23 / C++26 Copy Chapter

This open-access course is directed at those who are already familiar with C and object-oriented programming aiming for a proficiency level of C++ programming. The course covers the basics of C++ programming and moves on to advanced C++ semantics and concepts.

Key features:

• Free and frequently updated
• 29 lectures, 2000+ slides
• Includes the latest language standard concepts and features
• Practical teaching: non-verbose, short structured descriptions associated with code
• Minimal code examples for showing just a specific feature or issue without digressing
• Complementary language aspects: tools, coding conventions, project organization, and code optimization
• Experience-based: many aspects, examples, and problems come from real-world cases faced during my work as a software engineer

If you enjoy the course or you find it useful, please add a Star

Roadmap:

1. Move from Latex to Typst.
2. Fully-open source the material and allow direct contribution.

Table of Contents Copy Chapter

• Chapters
• Topics in Details
• Reporting Bugs 🐛 and Contributing
• Where the Course has been used
• License
• Author

CHAPTERS Copy Chapter

ALL-IN-ONE BOOK: modern-cpp.pdf (could be a few commits behind), html

TOPICS IN DETAILS Copy Chapter

1. Introduction

• A Little History of C/C++ Programming Languages.
• Areas of Application and Popularity.
• C++ Philosophy.
• C++ Weakness: C++ alternatives, Why switching to a new language is hard?.
• The Course.

2. Preparation

• Books and References.
• Slide Legend.
• What Editor/ IDE/Compiler Should I Use?.
• How to compile?.
• Hello World: I/O Stream.

3. Basic Concepts I - Type System, Fundamental Types, and Operators

• The C++ Type System: Type categories, Type properties.
• C++ Fundamental Types Overview: Arithmetic types, Non-standard arithmetic types, void type, nullptr.
• auto Keyword.
• C++ Operators: Operators precedence, Prefix/Postfix increment/decrement semantic, Assignment, compound, and comma operators, Spaceship operator <=>.

4. Basic Concepts II - Integral Types

• Integral Data Types: Suffix and Prefix, Fixed width integers, size_t, ptrdiff_t, uintptr_t.
• Arithmetic Operation Semantics: Saturation Arithmetic.
• Integer Undefined behavior: Signed overflow, Other cases.
• Integer Conversion Rules: Same size conversion, Integer conversion rule, Arithmetic operation promotion rules, Safe comparison functions, Arithmetic operation special cases.

5. Basic Concepts III - Floating-point Types

• Floating-point Types: Suffix, IEEE Floating-point standard and other representations, Normal/Denormal values, Infinity, Not a Number (NaN), Machine Epsilon, Units at the Last Place (ULP), Cheatsheet, Limits and useful functions, Arithmetic properties, Special values behavior, Undefined behavior, Detect floating-point errors.
• Floating-point Issues: Catastrophic cancellation, Floating-point comparison.

6. Basic Concepts IV - Entities and Control Flow

• Entities.
• Declaration and Definition.
• Enumerators.
• struct, Bitfield, union: struct, Anonymous and unnamed struct, Bitfield, union.
• Control Flow: if statement, for and while loops, Range-based for loop, switch, Initializing statement, goto, Avoid unused variable warning.
• Namespace: Explicit global namespace, namespace alias, using-declaration, using namespace-directive, inline namespace.
• Attributes: [[nodiscard]], [[indeterminate]], [[maybe_unused]], [[deprecated]], [[noreturn]].

7. Basic Concepts V - Memory Concepts

• Pointers: Pointer operations, Address-of operator &, struct member access, void pointer, Pointer conversion, Pointer arithmetic, Wild and dangling pointers.
• Fixed-size Array.
• References.
• Heap and Stack: Stack memory, new, delete, Non-allocating placement allocation, Non-throwing allocation, Memory leak.
• Initialization: Variable initialization, Uniform initialization, Array initialization, Structure initialization, Structure binding, Dynamic memory initialization.
• Const and Constant Expressions: Constants and literals, const, constexpr, constexpr Variables, constexpr Functions, constexpr objects, consteval, constinit.
• Conditional Constant Expressions:
• if constexpr, std::is constant evaluated(), if consteval.
• volatile Keyword.
• Explicit Type Conversion: static_cast, const_cast, reinterpret_cast, Type punning, std::bit_cast, Uniform initialization conversion, gls::narrow_cast.
• sizeof and alignof Operators: sizeof, alignof, sizeof/alignof operator applied to struct, [[no_unique_address]].

8. Basic Concepts VI - Functions and Preprocessing

• Functions: Pass by-value, Pass by-pointer, Pass by-reference, Function signature and overloading, Overloading and =delete, Default parameters.
• Function Pointer and Function Objects.
• Lambda Expressions: Capture list, Lambda expression and function relation, Parameter notes, Composability, Recursion, constexpr/consteval, template, mutable, Capture list and classes.
• Preprocessing: Preprocessors, Common errors, Source location macros, Conditional compiling macros, Stringizing operator (#), #error and #warning, #pragma, Token-pasting operator ##, Variadic macro.

9. Object-Oriented Programming I - Class Concepts

• C++ Classes: RAII idiom.
• Class Hierarchy.
• Access specifiers: Inheritance access specifiers, When use public/protected/private for data members?.
• Class Constructor: Default constructor, Class initialization, Uniform initialization for objects, Delegate constructor, explicit keyword.
• Copy Constructor.
• Class Destructor.
• Defaulted Constructors, Destructor, and Operators (= default).
• Class Keywords: this, static, const, mutable, using, friend, delete.

10. Object-Oriented Programming II - Polymorphism and Operator Overloading

• Polymorphism: C++ mechanisms for polymorphism, virtual methods, Virtual table, override keyword, final keyword, Common errors, Pure virtual method, Abstract class and interface.
• Inheritance Casting and Run-time Type Identification.
• Operator Overloading: Overview, Comparison operator <, Spaceship operator <=>, Subscript operator [], Multidimensional subscript operator [], Function call operator (), static operator [] and operator (), Conversion operator T(), Return type overloading resolution, Increment and decrement operators ++/--, Assignment operator =, Stream operator <<, Operator notes.
• C++ Object Layout: Aggregate, Trivial class, Standard-layout class, Plain old data (POD), Hierarchy.

11. Templates and Meta-programming I - Function Templates and Compile-Time Utilities

• Function Template: Overview, Template instantiation, Template parameters, Template parameter - default value, Overloading, Specialization.
• Template Variable.
• Template Parameter Types: Generic type notes, auto placeholder, Function type.
• Compile-Time Utilities: static_assert, using keyword, decltype keyword.
• Type Traits: Overview, Type traits library, Type manipulation.

12. Templates and Meta-programming II - Class Templates and SFINAE

• Class Template: Class specialization, Class template constructor.
• Constructor template automatic deduction (CTAD).
• Class Template - Advanced Concepts: Class + Function - specialization, Dependent names - typename and template keywords, Class template hierarchy and using, friend keyword, Template template arguments.
• Template Meta-Programming.
• SFINAE: Substitution Failure Is Not An Error: Function SFINAE, Class SFINAE.
• Variadic Template: Homogeneous variadic parameters, Folding expression, Variadic class template.
• C++20 Concepts: Overview, concept keyword, requires clause, requires expression, requires expression + clause, requires clause + expression, requires and constexpr, Nested requires.
• Template Debugging.

13. Translation Units I - Linkage and One Definition Rule

• Basic Concepts: Translation unit, Local and global scope, Linkage, Visibility.
• Storage Class and Duration: Storage duration, Storage class, static keyword, Anonymous namespace, extern keyword.
• Linkage of const and constexpr: Static initialization order fiasco.
• Linkage Summary.
• Dealing with Multiple Translation Units: Class in multiple translation units.
• One Definition Rule (ODR): Global variable issues, ODR - Point 3, inline functions/variables, constexpr and inline.
• ODR - Function Template: Cases, extern keyword.
• ODR - Class Template: Cases, extern keyword.
• ODR Undefined Behavior and Summary.

14. Translation Units II - Include, Module, and Namespace

• #include Issues: Include guard, Forward declaration, Circular dependencies, Common linking errors.
• C++20 Modules: Overview, Terminology, Visibility and reachability, Module unit types, Keywords, Global module fragment, Private module fragment, Header module unit, Module partitions.
• Compiling Multiple Translation Units: Fundamental compiler flags, Compile methods.
• Libraries in C++: Static library, Build static libraries, Using static libraries, Dynamic library, Build dynamic libraries, Using dynamic libraries, Application binary interface (ABI), Demangling, Find Dynamic library dependencies, Analyze object/executable symbols.

15. Code Conventions I

• C++ Project Organization: Project directories, Project files, "Common" project organization notes, Alternative - "Canonical" project organization.
• Coding Styles and Conventions: Overview, Popular coding styles.
• Header Files and #include: #include guard, #include syntax, Order of #include, Common header/source filename conventions.
• Preprocessing: Macro, Preprocessing statements.
• Variables: static global variables, conversions.
• Enumerators.
• Arithmetic Types: Signed vs. unsigned integral types, integral types conversion, Integral types: size and other issues, Floating-point types.
• Functions: Function parameters, Function arguments, function return values, Function specifiers, lambda expressions.
• Structs and Classes: struct vs. class, Initialization, Braced initializer lists, Special member functions, =default, =delete, Other issues, Inheritance, Style.

16. Code Conventions II

• auto.
• Templates and Type Deduction.
• Control Flow: Redundant control flow, if/else, Comparison, switch, for/while.
• Namespace: using namespace directive, Anonymous/unnamed namespace, Namespace and class design, Style.
• Modern C++ Features: Keywords, Features, Class, Library.
• Maintainability: Code comprehension, Functions, Template and deduction, Library.
• Portability.
• Naming: Entities, Variables, Functions, Style conventions, Enforcing naming styles.
• Readability and Formatting: Horizontal spacing, Pointers/References, Vertical spacing, Braces, Type decorators, Reduce code verbosity, Other issues.
• Code Documentation: Function documentation, Comment syntax, File documentation.

17. Debugging and Testing

• Debugging Overview: Errors, defects, and failures, Cost of software defects, Software defects classification,Program error and classification, Software defect analysis.
• Assertions: Run-time assertions, Contracts, std::stacktrace.
• Execution debugging: Breakpoints, Watchpoints / Catchpoints, Control flow, Stack and info, Print, Disassemble, std::breakpoint.
• Memory Debugging: valgrind.
• Hardening Techniques: Stack usage, Standard C library hardening, Standard C++ library hardening,Undefined behavior protections, Control flow protections.
• Sanitizers: Address sanitizer, Leak sanitizer, Memory sanitizers, Undefined behavior sanitizer, Type Sanitizer, Sampling-based sanitizer.
• Debugging Summary.
• Compiler Warnings.
• Static Analysis: Compiler-provided static analyzers, Open-source static analyzers, Proprietary static analyzers.
• Code Testing: Unit testing, Test-Driven Development (TDD), Code coverage, Fuzz testing.
• Code Quality: clang-tidy.
• Code Complexity: Cyclomatic complexity, Cognitive complexity.

18. Ecosystem - Cmake and Other Tools

• CMake: cmake and ctest
• Code Documentation: doxygen, Alternatives.
• Online Tools: AI-Powered code completion/IDE, Compilation and execution, Code transformation, Code benchmarking,
  Code search engine.
• Offline Tools: Code formatting, Code statistics, AST diff, Project visualization, Local code search, AST search,
  Font for coding.

19. Utilities

• View Introduction and std::span.
• std::mdspan: std::extends, Layout, std::layout_right, std::layout_left, std::layout_stride, std::layout_right_padded, std::layout_left_padded, Accessor.
• Strings and std::print: std::string, Conversion from/to numeric values, std::string_view, std::format, std::print.
• Math Libraries: <cmath> Math Library, <limits> Numerical Limits, <numbers> Mathematical Constants.
• Random Number: Basic concepts, C++ <random>, Seed, PRNG period and quality, Distribution, Recent algorithms and Performance, Quasi-random, True Random Number Generator (TRNG).
• Time Measuring: Wall-Clock time, User time, System time
• Std Class Templates: std::pair, std::tuple, std::variant, std::optional, std::any.
• Filesystem Library: Query methods, Modify methods.

20. Containers, Iterators, and Algorithms

• Containers and Iterators: Semantic.
• Sequence Containers: std::array, std::vector, std::deque, std::list, std::forward_list.
• Associative Containers: std::set, std::map, std::multiset.
• Container Adaptors: std::stack, std::queue, std::priority_queue.
• Implement a Custom Iterator: Implement a simple Iterator.
• Iterator Notes.
• Iterator Utility Methods: std::advance, std::next, std::prev, std::distance, Container access methods, Iterator traits.
• Algorithms Library: std::find_if, std::sort, std::accumulate, std::generate, std::remove_if.
• C++20 Ranges: Key concepts, Range view, Range adaptor, Range factory, Range algorithms, Range actions.

21. Advanced Topics I

• Move Semantic: lvalues and rvalues references, Move semantic, std::move, Class declaration semantic.
• Universal Reference and Perfect Forwarding: Universal reference, Reference collapsing rules, Perfect forwarding.
• Value Categories.
• &, && Ref-qualifiers and volatile Overloading.
• Copy Elision and RVO.
• Type Deduction: Pass by-reference, Pass by-pointer, Pass by-value, auto deduction, auto(x): Decay-copy.
• const Correctness.

22. Advanced Topics II

• Undefined Behavior: Illegal behavior, Platform specific behavior, unspecified behavior, Detecting undefined behavior.
• Error Handling: Recoverable error handling, Return code, C++ Exceptions, Defining custom exceptions, noexcept keyword, Memory allocation issues, Return code and exception summary, std::expected, Alternative error handling approaches.
• Smart pointers: std::unique_ptr, std::shared_ptr, std::weak_ptr.
• Concurrency: Thread methods, Mutex, Atomic, Task-based parallelism.

23. Optimization I - Basic Concepts

• Introduction: Moore's Law, Moore's Law limitations, Reasons for optimizing.
• Basic Concepts: Asymptotic complexity, Time-Memory trade-off, Developing cycle, Amdahl's Law, Throughput, Bandwidth, Latency, Performance bounds, Arithmetic intensity.
• Basic Architecture Concepts: Instruction throughput (IPC), In-Order, and Out-of-Order Execution, Instruction pipelining, Instruction-level parallelism (ILP), Little's law, Data-level parallelism (DLP) and vector instructions (SIMD), Thread-level parallelism (TLP), Single Instruction Multiple Threads (SIMT), RISC, CISC instruction sets.
• Memory Hierarchy: Memory hierarchy concepts, Memory locality, Core-to-core latency and thread affinity, Memory ordering model.

24. Optimization II - Code Optimization

• I/O Operations: printf, Memory mapped I/O, Speed up raw data loading.
• Memory Optimizations: Heap memory, Stack memory, constexpr vs. static constexpr, Cache utilization, Memory alignment, Memory Prefetch.
• Arithmetic Types: Data types, Arithmetic operations, Conversion, Floating-point, Compiler intrinsic functions, Value in a range, Lookup table.
• Control Flow: Branches, Branch Hints - [[likely]] / [[unlikely]], Signed/Unsigned integers, Loops, Loop hoisting, Loop unrolling, Assertions, Compiler hints [[assume]]/std::unreachable(), Recursion.
• Functions: Function call cost, Argument passing, Function inlining, Pure functions, Constant functions, Pointer aliasing.
• Object-Oriented Programming.
• Standard Library and Other Language Aspects.

25. Optimization III - Non-Coding Optimizations and Benchmarking

• Compiler Optimizations: About the compiler, Compiler optimization flags, Floating-point optimization flags, Linker optimization flags, Architecture flags, Help the compiler to produce better code, Profile-guided optimization (PGO and AutoFDO), Post-processing binary optimizer, Polyhedral optimizations.
• Compiler Transformation Techniques: Basic transformations, Loop unswitching, Loop fusion, Loop fission, Loop interchange, Loop tiling.
• Libraries and Data Structures.
• Performance Benchmarking: What to test?, Workload/Dataset quality, Metric evaluation.
• Stable Performance Measurement: Cache behavior, Stable CPU performance, Multi-thread considerations, Operating system considerations, Program memory layout, Measurement overhead, Compiler optimizations.
• Profiling: gprof, uftrace, callgrind, cachegrind, perf Linux profiler.
• Parallel Computing: Concurrency vs. parallelism, Performance scaling, Gustafson's Law, Parallel programming languages.

26. Software Design I - Basic Concepts (DRAFT)

• Books and References.
• Basic Concepts: Abstraction, interface, and module, Class Invariant.
• Software Design Principles: Separation of concern, Low coupling, high cohesion, Encapsulation and information hiding, Design by contract, Problem decomposition, Code reuse.
• Software Complexity: Software entropy, Technical debt.
• The SOLID Design Principles.
• Class Design: The class interface principle, Member functions vs. free functions, namespace functions vs. class static methods.
• BLAS GEMM Case Study.
• Owning Objects and Views.
• Value vs. Reference Semantics.
• Global Variables.

27. Software Design II - Design Patterns and Idioms (DRAFT)

• C++ Idioms: Rule of Zero, Rule of Three, Rule of Five.
• Design Pattern: Singleton, Pointer to IMPLementation (PIMPL), Curiously Recurring Template Pattern (CRTP), Template virtual functions.

28. Binary Size

• Binary Size Introduction:
• Compiler and Linker Techniques: Optimization flags, Debugging and runtime information flags, Symbol visibility, Exceptions flags, Linker flags, Link-Time Optimization (LTO), CMake support.
• Coding Aspects: Function Inlining, Function Visibility, Templates, Static Storage Duration, Linkage, Polymorphic classes, Exceptions, Header Inclusion.
• Binary Size Tools: nm and objdump, Bloaty, Executable packer.

29. Build Time

• Compile Time Introduction: The importance of build time, Causes of long build time.
• Compiler Aspects: Compiler flags, Optimized compiler builds.
• C++ Standard Version.
• Precompiled Header (PCH).
• Linker Aspects: Link-Time Optimization (LTO), Thin Link-Time Optimization (ThinLTO), Main linkers, Linker flags.
• Unity Build.
• Tools for Reducing Build Time: ninja, Compiler cache, Distributed compilation, RAM disk, Include-What-You-Use (IWYU).
• Function Inlining.
• Template: Template metaprogramming cost, extern template, constexpr variable vs. template structure + static Data member, Tag dispatching, Fold expressions, C++20 concepts, auto, using type aliasing.
• Other Aspects: C++20 modules, Overload resolution, other code aspects, Pointer Implementation (PIMPL), Include guard vs. #pragma once, Static vs. dynamic linking, Comments and formatting, External factors.
• Tools to Analyze Build Time: Clang build-time analysis, ninjatracing, Templight, Build Bench, Visual Studio - CompileScore, Visual Studio - C++ Build Insights.

Reporting Bugs 🐛 and Contributing Copy Chapter

Please see the CONTRIBUTING.md file for more information.

Where the Course has been used Copy Chapter

The Modern C++ Programming course was created in 2018 and adopted by the University of Verona, Italy. It is taught as part of the Bachelor's and Master's degree programmes in Computer Science, for three and two years respectively. The course has also been used to train interns at NVIDIA.

Have you adopted the course, or are you interested in using it in certain contexts? If so, please get in touch so that I can keep track of usage. I'm also willing to share the LaTeX source code (the Tyst version will be open-sourced on GitHub soon).

License Copy Chapter

This repository is dual-licensed:

• Course Content: All written materials, slides, and images are licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
• Source Code: All code examples and scripts are licensed under the MIT License.

Author Copy Chapter

Federico Busato, federico-busato.github.io

• 🌐 LinkedIn: www.linkedin.com/in/federico-busato/
• 🦋 Bluesky: fbusato.bsky.social

2. Official Technical Reference & Guides (federico-busato/federico-busato.github.io) Copy Chapter

al-folio

User community Copy Chapter

The vibrant community of al-folio users is growing!
Academics around the world use this theme for their homepages, blogs, lab pages, as well as webpages for courses, workshops, conferences, meetups, and more.
Check out the community webpages below.
Feel free to add your own page(s) by sending a PR.

| Academics | ★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★
★

★ |
| --- | --- |
| Labs | ★
★
★
★
★
★
★ |
| Courses | CMU PGM (S-19)
CMU DeepRL (F-19, S-20, F-20, S-21, F-21, S-22)
CMU MMML (F-20, F-22)
CMU AMMML (S-22, S-23)
CMU ASI (S-23)
CMU Distributed Systems (S-21) |
| Conferences & workshops | ICLR Blog Post Track (2023, 2024)
ML Retrospectives (NeurIPS: 2019, 2020; ICML: 2020)
HAMLETS (NeurIPS: 2020)
ICBINB (NeurIPS: 2020, 2021)
Neural Compression (ICLR: 2021)
Score Based Methods (NeurIPS: 2022)
Images2Symbols (CogSci: 2022)
Medical Robotics Junior Faculty Forum (ISMR: 2023)
Beyond Vision: Physics meets AI (ICIAP: 2023)
Workshop on Diffusion Models (NeurIPS: 2023) |

Lighthouse PageSpeed Insights Copy Chapter

Table Of Contents Copy Chapter

• al-folio
  • User community
  • Lighthouse PageSpeed Insights
  • Table Of Contents
  • Getting started
  • Installing
  • Customizing
  • Features
    • Light/Dark Mode
    • CV
    • People
    • Publications
    • Collections
    • Layouts
      • The iconic style of Distill
      • Full support for math & code
      • Photos, Audio, Video and more
    • Other features
      • GitHub's repositories and user stats
      • Theming
      • Social media previews
      • Atom (RSS-like) Feed
      • Related posts
  • FAQ
  • Contributing
    • Maintainers
    • All Contributors
  • License

Getting started Copy Chapter

Want to learn more about Jekyll? Check out this tutorial. Why Jekyll? Read Andrej Karpathy's blog post!

Installing Copy Chapter

For instalation details please refer to INSTALL.md.

Customizing Copy Chapter

For customization details please refer to CUSTOMIZE.md.

Features Copy Chapter

Light/Dark Mode Copy Section

This template has a built-in light/dark mode. It detects the user preferred color scheme and automatically switches to it. You can also manually switch between light and dark mode by clicking on the sun/moon icon in the top right corner of the page.

CV Copy Section

There are currently 2 different ways of generating the CV page content. The first one is by using a json file located in assets/json/resume.json. It is a known standard for creating a CV programmatically. The second one, currently used as a fallback when the json file is not found, is by using a yml file located in _data/cv.yml. This was the original way of creating the CV page content and since it is more human readable than a json file we decided to keep it as an option.

What this means is, if there is no resume data defined in _config.yml and loaded via a json file, it will load the contents of _data/cv.yml as fallback.

People Copy Section

You can create a people page if you want to feature more than one person. Each person can have its own short bio, profile picture, and you can also set if every person will appear at the same or opposite sides.

Publications Copy Section

Your publications' page is generated automatically from your BibTex bibliography. Simply edit _bibliography/papers.bib. You can also add new *.bib files and customize the look of your publications however you like by editing _pages/publications.md. By default, the publications will be sorted by year and the most recent will be displayed first. You can change this behavior and more in the Jekyll Scholar section in _config.yml file.

You can add extra information to a publication, like a PDF file in the assets/pdf/ directory and add the path to the PDF file in the BibTeX entry with the pdf field. Some of the supported fields are: abstract, altmetric, arxiv, bibtex_show, blog, code, dimensions, doi, eprint, html, isbn, pdf, pmid, poster, slides, supp, video, and website.

Collections Copy Section

This Jekyll theme implements collections to let you break up your work into categories. The theme comes with two default collections: news and projects. Items from the news collection are automatically displayed on the home page. Items from the projects collection are displayed on a responsive grid on projects page.

You can easily create your own collections, apps, short stories, courses, or whatever your creative work is. To do this, edit the collections in the _config.yml file, create a corresponding folder, and create a landing page for your collection, similar to _pages/projects.md.

Layouts Copy Section

al-folio comes with stylish layouts for pages and blog posts.

The iconic style of Distill

The theme allows you to create blog posts in the distill.pub style:

For more details on how to create distill-styled posts using <d-*> tags, please refer to the example.

Full support for math & code

al-folio supports fast math typesetting through MathJax and code syntax highlighting using GitHub style. Also supports mermaid diagrams and TikZ figures.

Photos, Audio, Video and more

Photo formatting is made simple using Bootstrap's grid system. Easily create beautiful grids within your blog posts and project pages, also with support for video and audio embeds:

Other features Copy Section

GitHub's repositories and user stats

al-folio uses github-readme-stats and github-profile-trophy to display GitHub repositories and user stats on the /repositories/ page.

Edit the _data/repositories.yml and change the github_users and github_repos lists to include your own GitHub profile and repositories to the /repositories/ page.

You may also use the following codes for displaying this in any other pages.

{% if site.data.repositories.github_users %}

  {% for user in site.data.repositories.github_users %}
    {% include repository/repo_user.html username=user %}
  {% endfor %}

{% endif %}


{% if site.repo_trophies.enabled %}
{% for user in site.data.repositories.github_users %}
  {% if site.data.repositories.github_users.size > 1 %}
  <h4>{{ user }}</h4>
  {% endif %}
  
  {% include repository/repo_trophies.html username=user %}
  
{% endfor %}
{% endif %}


{% if site.data.repositories.github_repos %}

  {% for repo in site.data.repositories.github_repos %}
    {% include repository/repo.html repository=repo %}
  {% endfor %}

{% endif %}

Theming

A variety of beautiful theme colors have been selected for you to choose from. The default is purple, but you can quickly change it by editing the --global-theme-color variable in the _sass/_themes.scss file. Other color variables are listed there as well. The stock theme color options available can be found at _sass/_variables.scss. You can also add your own colors to this file assigning each a name for ease of use across the template.

Social media previews

al-folio supports preview images on social media. To enable this functionality you will need to set serve_og_meta to true in your _config.yml. Once you have done so, all your site's pages will include Open Graph data in the HTML head element.

You will then need to configure what image to display in your site's social media previews. This can be configured on a per-page basis, by setting the og_image page variable. If for an individual page this variable is not set, then the theme will fall back to a site-wide og_image variable, configurable in your _config.yml. In both the page-specific and site-wide cases, the og_image variable needs to hold the URL for the image you wish to display in social media previews.

Atom (RSS-like) Feed

It generates an Atom (RSS-like) feed of your posts, useful for Atom and RSS readers. The feed is reachable simply by typing after your homepage /feed.xml. E.g. assuming your website mountpoint is the main folder, you can type yourusername.github.io/feed.xml

Related posts

By default, there will be a related posts section on the bottom of the blog posts. These are generated by selecting the max_related most recent posts that share at least min_common_tags tags with the current post. If you do not want to display related posts on a specific post, simply add related_posts: false to the front matter of the post. If you want to disable it for all posts, simply set enabled to false in the related_blog_posts section in _config.yml.

FAQ Copy Chapter

For frequently asked questions, please refer to FAQ.md.

Contributing Copy Chapter

Contributions to al-folio are very welcome! Before you get started, please take a look at the guidelines.

If you would like to improve documentation, add your webpage to the list below, or fix a minor inconsistency or bug, please feel free to send a PR directly to master. For more complex issues/bugs or feature requests, please open an issue using the appropriate template.

Maintainers Copy Section

Our most active contributors are welcome to join the maintainers team. If you are interested, please reach out!

All Contributors Copy Section

License Copy Chapter

The theme is available as open source under the terms of the MIT License.

Originally, al-folio was based on the *folio theme (published by Lia Bogoev and under the MIT license). Since then, it got a full re-write of the styles and many additional cool features.