This repository is a template and guide for creating SparkFun Arduino Libraries. It contains the necessary files and structure to create a new Arduino library repository that follows the SparkFun standards and practices for Arduino libraries.
When creating a repository, the preferred method is to create an empty repository and then copy in desired resources from this HowTo repository as needed.
- Create a new repository on GitHub with the desired name for the library, following the template SparkFun__Arduino_Library. When creating the repository, select the option to create a README.md file and a MIT License file. This will create the initial files for the repository and set up the license for the repository.
- Once the repository created, the first step is to create branch - specifically a develop branch. This branch is used to stage changes and updates to the library before they are merged into the main branch. All of the initial development is performed on the develop branch, and then a GitHub PR is used to support the initial code review of the repository.
- Clone the repository to your local machine and switch to the develop branch.
Note
The HowTo repository is not used as a GitHub template to create a new repository due to how GitHub displays an annoying banner on repository created from a template.
The How To Repository (this repository) contains an example README.md file - README_Example.md. This provides a easily modified file to build a repository README around.
SparkFun Arduino Libraries by default are published using the MIT OpenSource License. To attribute the repository with this license do the following:
- In the root of the repository, include the file LICENSE.md (or LICENSE, but as .md it renders better on-line)that contains the text of the MIT license
- When creating the repository, you can specify a license type of MIT and this file is created by GitHub
At the bottom of the README.md file, include the following text to indicate the license for the repository:
## License Information
This product is ***open source***!
This product is licensed using the [MIT Open Source License](https://opensource.org/license/mit)
For each source file created, include the following text at the comment header at the top of the file:
/*
* @date 2026
* @copyright Copyright (c) 2026, SparkFun Electronics Inc. This project is released under the MIT License.
*
* SPDX-License-Identifier: MIT
*/
Change the date and copyright date value as needed.
To brand the repository for a library, a "splash" image is created and is the first element of the README.md file.
The Splash Image for this repository:
The image uses one of the template image files contained in the docs/images folder. To create a specific image, perform the following steps.
- Select the image template to use from HowTo - make a local copy of this file
- Open this file in your desired image editing tool (i.e. Photoshop, Pixelmator, GIMP ...etc).
- Add the name of the repository item on the left section of the image.
- Add an image of the target product as well as a tile for the board in the white area of the image
- Save the image and add it to the "docs/images" folder of the new repository.
- Set this image name in the linked image at the top of your repo README.md file
Additionally, upload the image as the social image for the new repository. To do this, perform the following:
- Navigate to the Settings page for the new repository
- In the General Section, under the section Social preview select the EditUpload button and the presented upload file entry.
- Select the local copy of the Splash Image created for the repository
The file is uploaded and available for the repo.
Note
The social image is used to create preview tiles on the SparkFun Documentation landing page located at docs.sparkfun.com
The README.md file is the main landing page for the repository and should include the following sections:
- Splash Image
- Repository Description
- Badges (i.e. license, release version, documentation build status ...etc)
- Library Description
- Repository Contents
- Documentation
- Products That Use This Library
- License Information
SparkFun publishes product documentation using GitHub Pages. For product getting started and overview guides, Docusaurus is used. For Code libraries - like this Arduino Library HowTo - the doxygen system is used.
The first step is adding doxygen comments to the source code files. This is done by adding special comment blocks to the source code files that are then parsed by doxygen to generate the documentation. See doxygen for specific details, or just use your favorite AI to add doxygen enable comments to the library code.
First copy all the contents of the ./docs directory of this repository to the new repository. This includes the doxygen configuration file, HTML custom additions and a custom css (doxygen-awesome).
On a Unix/macos system this can be done with the following command:
cp -R ./docs /path/to/new/repositoryNext, the doxygen configuration file needs to be updated to reflect the new repository. Open the file Doxyfile, which is located in the docs/doxygen folder and called doxygen-config*. All updates that are made involve setting the name of this repository and and the name of the library. The following fields need to be updated:
- PROJECT_NAME
- PROJECT_BRIEF
That's it.
The doxygen-awesome-css is a custom CSS sub-repository is used to style the generated documentation. This file is located in the docs/doxygen folder and is called doxygen-awesome.css. To enable proper operation, the current repository is removed and re-linked into this repo. This is done by performing the following steps:
- Navigate to the docs/doxygen folder in a terminal
- Remove the current doxygen-awesome-css folder by running the following command:
rm -rf doxygen-awesome-css- Link the doxygen-awesome-css repository into this folder by running the following command:
git submodule add https://github.com/jothepro/doxygen-awesome-css.git
cd doxygen-awesome-css
git checkout v2.4.2- Commit the changes to the repository and push to GitHub
Note - for more details concerning doxygen-awesome-css, see the official repository located at https://github.com/jothepro/doxygen-awesome-css
In the folder docs/doxygen/doxygen-custom, the header.html file is used to add a link to the generated documentation page header. This fancy link points to the github repository for the library.
To update the link and title, the file must be edited, replacing all "SparkFun" entries and links, with titles and links for the new library.
The first step is to enable GitHub Pages support on the new repository. This is done on the Settings > Pages section of the new repository. The following is done:
- Set Build Source to GitHub Actions
- Check the box for Enforce HTTPS
The documentation is built using the GitHub Action located in the .github/workflows/build-deploy-ghpages.yml file. To enable this action, the following steps are performed:
- Copy this workflow from this How To repository to the new repository
- If desired to build automatically after a check in, un-comment the push event trigger for the workflow.
On the main code page of the repository, the "About" section (upper right side of the page) contains meta information about the repository and also sets the topics/tags that are used to automatically add the repository to the sparkfun documentation landing page (docs.sparkfun.com).
The set About information, select the gear icon in the section. From here, the following sections are updated
Add a detailed, one sentence description for the repository. This is often the same sentence used in the libraries.properties file.
Select the Use your GitHub Pages Website option for the repository website. NOTE: If the website is not https enabled, check your GitHub pages settings for the repository and ensure the enforce HTTPS option is checked.
The topics section should be setup to match what is needed for the SparkFun documentation landing page. For the specifics, consult the documentation landing page readme file.