Import, share and publish your README like a pro

A README made in Profile README Studio is plain Markdown that GitHub shows as usual. It also carries small invisible markers that let the studio turn it back into blocks, exactly as you left them. This lesson explains the markers and every way to move your work in and out of the studio.

#Know the markers

Open Markdown above the preview. The first line is a settings marker, and every block starts with its own marker:

<!-- studio:settings user=octocat theme=auto hl=2 border=hide light=github-light -->
<!-- studio:header -->
# Hi, I'm Octo
<!-- studio:stats+langs -->
...

GitHub hides HTML comments, so visitors never see them. The rules are simple:

• <!-- studio:TYPE --> starts a block, until the next marker
• Two cards side by side share one marker joined with +
• Some markers carry settings, like <!-- studio:blog feed=https://dev.to/feed/you count=5 -->; keep them as written
• Text outside any marker is kept as a Markdown block. Nothing is thrown away

You only need these rules if you edit the Markdown by hand. As long as the markers stay, the studio can read your README back.

#Import any README

Click Import in the top bar. Four ways in:

• Fetch it from GitHub: reads README.md from your profile repository, straight from your browser
• Or fill from your resume: a PDF, read in your browser
• Or open a layout file: a .json file saved from the studio; you can also drop it on the window
• Or paste the markdown

A README made in the studio comes back block for block. A README made elsewhere is converted as far as possible: known widgets (stats, streak, trophies, skill icons, typing text, badges, pin cards) become editable blocks, and everything else is kept as Markdown blocks.

#Share a layout

Your layout autosaves in your browser, and the address bar always holds a link to it. Share in the top bar copies that link. Whoever opens it gets your layout to change freely, without touching yours.

For a backup that does not depend on a link, use Save layout file in Export: every block and setting in one .json file, to open later with Import on any computer.

#Publish straight to GitHub

Publish for me in Export commits the README, its pictures and the workflow it needs to your profile repository in one click. It needs a fine-grained personal access token:

1. Click the link in the studio to create a token on GitHub
2. Under Repository access, pick Only select repositories and choose your profile repository
3. Under Permissions, set Contents to Read and write, and Workflows too when your README comes with the profile workflow (the studio says so)
4. Click Generate token, copy it, and paste it into the studio

The token only works for that one repository and expires on its own. It stays in this browser tab and is sent only to api.github.com: it is never saved in your layout, share links or exports, and closing the tab forgets it. You can delete it on GitHub any time.

If the repository is private, the studio publishes and reminds you to make it public, since a private profile README is not shown.

#Choose your workflow

The last lesson turns everything around: a profile for a GitHub organization.