Add a source
A built-in source is a C# class in Maki.Sources. First check whether the site fits a custom source: a JSON definition (CSS selectors, regular expressions or JSON paths) that admins set up in the app with no code.
Write a built-in source when the site needs logic a definition cannot express, such as scrambled pages or signed API calls. Nothing in a definition runs as code.
The interface
Section titled “The interface”Implement ISource from src/Maki.Core/Sources/ISource.cs:
Name: a stable lowercase key such asmangadex. It is stored inSourceMapping.SourceName, so it cannot change later.DisplayNameandBaseUrl.Capabilities:SourceCapabilities.Noneunless the site needs FlareSolverr (NeedsFlareSolverr) or honours a language filter (SupportsLanguageFilter).SearchAsync,GetSeriesAsync,ListChaptersAsyncandGetPagesAsync.
Override these defaults only when they differ: Kind (aggregator), Content (manga), Rating (general), SupportedLanguages (English), CoverHosts for images served from another domain, ResolveSeriesIdFromUrl and GetExternalIdsAsync.
Example: Asura
Section titled “Example: Asura”src/Maki.Sources/Asura/AsuraSource.cs is a small JSON API source. Use it as the template.
- It takes an
IHttpClientFactoryand a named client, set up insrc/Maki.Api/Program.csnext to the otherAddHttpClientcalls with the site’s base address and headers. - It packs what it needs into the chapter id, so
GetPagesAsynccan rebuild the request from the two ids alone. - Premium chapters that have not unlocked stay in the list.
GetPagesAsyncthrowsChapterLockedExceptionso the download retries later.
- Create
src/Maki.Sources/<Site>/<Site>Source.csin namespaceMaki.Sources.<Site>. - Implement
ISource. Return chapters throughSourceChapterList.Normalize, which removes duplicates by number, volume and language, and by title when a chapter has no number. - Register it in
src/Maki.Api/Program.cswithbuilder.Services.AddSingleton<ISource, <Site>Source>();, next to the other source lines. Add a named HTTP client there if the source needs one. - Add a row to the table in
docs/sources.md, and to the copy of that table in the “Show all sources” dropdown inREADME.md. Bump the built-in count inREADME.mdtoo. - Add tests in
tests/Maki.Sources.Tests/<Site>SourceTests.cs. - Run them with
dotnet test tests/Maki.Sources.Tests.
Build the source on FakeHttpClientFactory, which answers requests with canned responses keyed by a substring of the URL.
- Put recorded HTML or JSON in
tests/Maki.Sources.Tests/Fixtures/and read it withFakeHttpClientFactory.Fixture("name.html"). Short inline JSON works too, as in Asura’s tests. - Cover search, the chapter list and the page list.
- Include a page response without the expected payload. It should throw, not return an empty list.
Things that catch people out
Section titled “Things that catch people out”- Tag each chapter with the language the site reports. Do not hardcode
"en". Language is half of a chapter’s identity and goes into the file name when two languages of one chapter are downloaded. - Set
Kind,ContentandRatingwhen the defaults are wrong. A scanlation group isSourceKind.Scanlator. They drive the tags the UI shows. GetPagesAsyncruns at download time. Resolve page URLs there, and return the headers each page needs inPageRequest.Headers.- Empty list and exception differ. An empty list means the site lists no pages. A response with no page payload throws
InvalidOperationExceptionnaming the URL. - Images on another domain need
CoverHosts. The cover proxy only fetches hosts the source lists, and a blocked host is logged with its name.
Read src/Maki.Sources/CLAUDE.md first. It records what other sites have needed, such as Cloudflare clearance, rate limits and residential IPs.