{"id":156,"date":"2025-11-20T00:00:00","date_gmt":"2025-11-20T08:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/aspire\/?p=156"},"modified":"2025-11-24T07:52:42","modified_gmt":"2025-11-24T15:52:42","slug":"migrating-from-microsoft-learn-to-aspire-dev","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/aspire\/migrating-from-microsoft-learn-to-aspire-dev\/","title":{"rendered":"Migrating from Microsoft Learn to aspire.dev"},"content":{"rendered":"<blockquote>\n<p><strong>Liked this blog post?<\/strong> It was originally posted on David Pine&#8217;s blog, <a href=\"https:\/\/davidpine.net\">https:\/\/davidpine.net<\/a>, check out more content there!<\/p>\n<\/blockquote>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/aspire\/wp-content\/uploads\/sites\/90\/2025\/11\/Migration-integration-article.webp\" alt=\"Migration PR overview\" \/><\/p>\n<p>When my team (the Aspire team) decided to migrate all Aspire content from Microsoft Learn to the shiny new <a href=\"https:\/\/aspire.dev\/\">aspire.dev<\/a> site, we knew we\u2019d signed up for a marathon. You may have noticed banners atop both Microsoft Learn: Aspire and aspire.dev announcing the migration\u2026<\/p>\n<h5><a href=\"https:\/\/learn.microsoft.com\/dotnet\/aspire\/\">Microsoft Learn: Aspire<\/a><\/h5>\n<p><img decoding=\"async\" src=\".\/Aspire-documentation-on-Learn.png\" alt=\"Migration process overview\" \/><\/p>\n<h5><a href=\"https:\/\/aspire.dev\/get-started\/welcome\/\">aspire.dev: Welcome page<\/a><\/h5>\n<p><img decoding=\"async\" src=\".\/Welcome-aspiredev.png\" alt=\"aspire.dev welcome page\" \/><\/p>\n<p>The initial estimate? <strong>Three months<\/strong> of dedicated work\u2014an entire corporate quarter of toil. Picture this: hundreds of published articles, each one demanding careful surgery to convert syntax, restructure directories, update messaging, revamp layouts, adapt to new tooling, and genuflect to new conventions.<\/p>\n<p>Yeah, no thanks. Then I discovered GitHub Copilot\u2019s <strong>Plan<\/strong> mode in VS Code \ud83e\udd13.<\/p>\n<h3>Enter Planning Mode<\/h3>\n<p>GitHub Copilot\u2019s <a href=\"https:\/\/code.visualstudio.com\/docs\/copilot\/chat\/chat-planning\">Planning mode<\/a> fundamentally changed the game. Instead of manually editing each file (soul-crushing), or wrestling with some other AI tool that kept hallucinating nonsense (equally soul-crushing), I could formalize a comprehensive plan that spelled out:<\/p>\n<ul>\n<li><strong>Syntax changes:<\/strong> Converting from Microsoft Learn&#8217;s documentation format to the new aspire.dev conventions, using MDX, custom Astro components, and Starlight design system elements<\/li>\n<li><strong>Directory updates:<\/strong> Reorganizing file structures to match the new site architecture<\/li>\n<li><strong>Convention alterations:<\/strong> Ensuring consistency across all integration documents<\/li>\n<li><strong>Metadata transformations:<\/strong> Updating front matter and document properties<\/li>\n<li><strong>Component migration:<\/strong> Replacing DocFX-specific syntax (like zone pivots and image directives) with custom Astro &amp; Starlight components\u2014specifically the <code>PivotSelector<\/code> and <code>Pivot<\/code> components I built for the new site<\/li>\n<li><strong>Domain knowledge encoding:<\/strong> Translating my deep understanding of both the old and new documentation systems into a prompt (plan) that could be iteratively refined and executed<\/li>\n<\/ul>\n<p>This wasn\u2019t just a simple find-and-replace operation\u2014if only. We were fundamentally rearchitecting how we write docs, migrating from DocFX with markdown to a modern Astro &amp; Starlight stack. The secret sauce? Encoding my domain knowledge\u2014every quirk, pattern, and gotcha from both systems\u2014into a plan that the AI could execute consistently across hundreds of files.<\/p>\n<p>The beauty of Planning mode is its ability to transform impossible into manageable. You break down massive tasks into bite-sized, reviewable steps, then execute them systematically. Applying first principles thinking, I treated this migration as a series of transformations, each with crystal-clear input and output expectations.<\/p>\n<p>Normally, I\u2019d label this \u201cbusy work\u201d\u2014that special brand of mundane, repetitive, mind-numbing tedium that makes you question your career choices. I have better things to do, like actually building features or, you know, enjoying coffee. But with AI assistance? Suddenly this tedious slog transformed into a high-leverage activity worthy of my time.<\/p>\n<h3>The Execution<\/h3>\n<p>The migration happened across a series of pull requests, but the crown jewel was <a href=\"https:\/\/github.com\/microsoft\/aspire.dev\/pull\/49\">Pull Request #49<\/a>\u2014the bulk migration of all integrations, community toolkit integrations, and diagnostics documentation from Microsoft Learn to aspire.dev. Think of it as moving an entire library across town, except every book needs to be rewritten in a new language while maintaining the same story.<\/p>\n<p>This wasn\u2019t just a typical pull request. The diff tells the story:<\/p>\n<ul>\n<li><strong>+18,558 lines added<\/strong><\/li>\n<li><strong>\u22121,995 lines removed<\/strong><\/li>\n<\/ul>\n<p>We\u2019re talking about transforming nearly 20,000 lines of documentation in a single, coherent pull request. The added lines represent the new MDX format with custom Astro components, while the removed lines were the old DocFX markdown being shown the door.<\/p>\n<p><img decoding=\"async\" src=\".\/Migration-2-of-several.png\" alt=\"PR 2 of several\" \/><\/p>\n<p>But that single PR was just one chapter of the story. The complete migration spanned multiple pull requests, each tackling different aspects of the documentation ecosystem. When you zoom out and look at the total impact across all related PRs, the numbers become even more staggering:<\/p>\n<ul>\n<li><strong>+668 lines added across supporting changes<\/strong><\/li>\n<li><strong>\u2212114,030 lines removed from the source repository<\/strong><\/li>\n<\/ul>\n<p>Yes, you\u2019re reading that correctly: <a href=\"https:\/\/github.com\/dotnet\/docs-aspire\/pull\/5748\">over <strong>114,000 lines deleted.<\/strong><\/a><\/p>\n<blockquote>\n<h6>\u2795 Understanding the deltas<\/h6>\n<p>The massive deletion count reflects more than just content migration. We also removed entire snippet directories that were previously referenced as raw code blocks within the docs-aspire content. This approach allowed us to run compilation of the code\u2014a nice-to-have feature that validated our examples. We\u2019ll evaluate implementing a similar compilation validation system in aspire.dev at some future point.<\/p>\n<\/blockquote>\n<h4>By the Numbers<\/h4>\n<p>To understand the scale of this migration, here&#8217;s what we were working with in the source repository:<\/p>\n<table>\n<thead>\n<tr>\n<th><strong>Category<\/strong><\/th>\n<th><strong>Count<\/strong><\/th>\n<th><strong>Notes<\/strong><\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><strong>Markdown files (articles)<\/strong><\/td>\n<td>352<\/td>\n<td>The primary documentation content<\/td>\n<\/tr>\n<tr>\n<td><strong>YAML files<\/strong><\/td>\n<td>42<\/td>\n<td>Configuration and metadata files<\/td>\n<\/tr>\n<tr>\n<td><strong>Images<\/strong><\/td>\n<td>353<\/td>\n<td>332 PNG, 15 SVG, 6 GIF<\/td>\n<\/tr>\n<tr>\n<td><strong>C# projects<\/strong><\/td>\n<td>153<\/td>\n<td>Sample code and integration examples<\/td>\n<\/tr>\n<tr>\n<td><strong>Total files<\/strong><\/td>\n<td>3,857<\/td>\n<td>Complete repository inventory<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>The repository was a sprawling ecosystem of documentation, code samples, and assets. Beyond the core docs:<\/p>\n<ul>\n<li><strong>348<\/strong> C# source files<\/li>\n<li><strong>151<\/strong> Razor components<\/li>\n<li><strong>120<\/strong> CSS files<\/li>\n<li><strong>46<\/strong> Bicep templates<\/li>\n<li><strong>45<\/strong> solution files<\/li>\n<li>And <strong>28 more file types<\/strong> scattered about<\/li>\n<\/ul>\n<blockquote>\n<h6>\ud83e\udd2f These stats brought to you by, GitHub Copilot CLI<\/h6>\n<p>A simple query on the command line using GitHub Copilot CLI helped tally up the file types and counts. Instead of writing some elaborate script, I simply asked Copilot to break down the totals based on a commit that represented the pre-migration state of the repository. It figured out the rest, but basically checked out the repo at that commit, scanned the file system, and produced a neat summary of file types and counts.<\/p>\n<\/blockquote>\n<p>Not every file needed migration\u2014compiled binaries and build artifacts got to sit this one out\u2014but even focusing solely on documentation and supporting files meant tackling a Herculean task. <strong>Over 350 articles<\/strong> demanded careful conversion, each one a special snowflake with its own syntax quirks, metadata peculiarities, and structural idiosyncrasies.<\/p>\n<p>Every single integration was successfully migrated in a fraction of the anticipated time. What would have been three months of drudgery became one intense, productive day.<\/p>\n<h3>The power of context switching<\/h3>\n<p>Here\u2019s where things get genuinely impressive: AI-assisted development freed me from the tyranny of continuous focus. I spent a full day on this migration, but I wasn\u2019t shackled to my desk like some modern-day Prometheus. Instead, I could:<\/p>\n<ol>\n<li><strong>Set up the plan<\/strong> and let Copilot churn through a batch of files<\/li>\n<li><strong>Step away<\/strong> for meetings, coffee, or existential contemplation<\/li>\n<li><strong>Return and review<\/strong> the changes at my leisure<\/li>\n<li><strong>Course-correct<\/strong> and refine the approach when needed<\/li>\n<li><strong>Repeat<\/strong> until victory<\/li>\n<\/ol>\n<p>The AI didn\u2019t lose its place or forget what it was doing. The plan remained rock-solid consistent, and I could \u201ctame\u201d the AI whenever it started wandering off into creative territory (read: making stuff up).<\/p>\n<h4>AI everywhere<\/h4>\n<p>Look, I\u2019ll be honest\u2014AI has become an integral part of my development workflow. GitHub Copilot isn\u2019t just a tool; it\u2019s genuinely everywhere I work:<\/p>\n<ul>\n<li><a href=\"https:\/\/docs.github.com\/en\/copilot\/github-copilot-in-the-cli\/about-github-copilot-in-the-cli\"><strong>GitHub Copilot CLI:<\/strong><\/a> For those command-line flags I can never remember, and powerful file system searches when Windows Explorer claims something doesn\u2019t exist (spoiler: it does)<\/li>\n<li><a href=\"https:\/\/docs.github.com\/en\/copilot\/how-tos\/use-copilot-agents\/manage-agents\"><strong>GitHub.com\u2019s Copilot:<\/strong><\/a> For constructive and valuable code reviews, and pull requests that often do as you ask<\/li>\n<li><a href=\"https:\/\/code.visualstudio.com\/docs\/copilot\/copilot-coding-agent\"><strong>VS Code\u2019s Copilot Agent<\/strong><\/a> <strong>and<\/strong> <a href=\"https:\/\/code.visualstudio.com\/docs\/copilot\/chat\/chat-planning\"><strong>Planning modes:<\/strong><\/a> For breaking down complex tasks into manageable steps<\/li>\n<\/ul>\n<p>It\u2019s not just assistance\u2014it\u2019s like having a tireless colleague who\u2019s always ready to help, never complains, and can process thousands of files without breaking a sweat. The \u201cCopilot\u201d branding? Spot on. \ud83e\udd16<\/p>\n<h3>Lessons learned<\/h3>\n<p><strong>Start with a solid plan:<\/strong> The <code>.github\/prompts\/update-integrations.prompt.md<\/code> file became my north star, my constitution, my single source of truth. Time invested upfront documenting the migration requirements paid dividends throughout\u2014like compound interest, but for productivity.<\/p>\n<p><strong>Review in batches:<\/strong> Don\u2019t try to boil the ocean. I broke the work into logical groups of integrations, making the review process actually manageable instead of overwhelming. This approach caught issues early, when they were cheap to fix.<\/p>\n<p><strong>Trust but verify:<\/strong> AI is incredibly powerful, almost magical even, but human oversight remains non-negotiable. In my experience, about 90% of the migrations were perfect, with the remaining 10% needing minor touch-ups. Those are excellent odds, but that 10% matters.<\/p>\n<p><strong>Document your process:<\/strong> By capturing the prompt and approach in the repository itself, we\u2019ve created a reusable template for future migrations or similar large-scale updates. Future you (or future colleagues) will thank present you.<\/p>\n<h3>From three months to a few days<\/h3>\n<p>Let that sink in for a moment: <strong>three months compressed into a few partial days<\/strong>. The contrast isn\u2019t just striking\u2014it\u2019s borderline absurd. But this isn\u2019t merely a speed story. It\u2019s about maintaining consistency across hundreds of documents, reducing human error to near-zero, and liberating valuable engineering time for work that actually requires human creativity and strategic thinking.<\/p>\n<p>GitHub Copilot\u2019s Planning mode didn\u2019t just make me faster; it made the entire migration more reliable, more maintainable, and frankly, more sane. As we continue evolving aspire.dev, having this documented approach means we can confidently tackle site-wide changes without inducing existential dread.<\/p>\n<h3>The bigger picture<\/h3>\n<p>The future of developer productivity isn\u2019t just about AI writing code\u2014that\u2019s table stakes. It\u2019s about AI helping us plan, execute, and manage large-scale transformations with unprecedented efficiency. It\u2019s about turning the tedious into the tractable, the impossible into the inevitable.<\/p>\n<p>This migration proved something important: with the right tools and approach, we can accomplish in hours what used to take months. The question isn\u2019t whether AI will transform how we work\u2014it already has. The question is: what will you build with all that newfound time?<\/p>\n<p>The journey doesn\u2019t end here\u2014it\u2019s just beginning. I\u2019m building aspire.dev in the open, and this migration is merely chapter one of a much larger story. Every contribution, every improvement, every lesson learned becomes part of our collective knowledge.<\/p>\n<p>Want to be part of shaping the future of Aspire documentation? The doors are wide open, the tools are evolving, and there\u2019s room at the table for everyone who shares our vision of making cloud-native development more accessible, more powerful, and more delightful.<\/p>\n<p>Together, we\u2019re not just building documentation\u2014we\u2019re building the foundation for how developers will understand and leverage distributed applications for years to come.<\/p>\n<p><a href=\"https:\/\/aspire.dev\/community\/contributor-guide\/\">Join us: Contributor guide for <code>aspire.dev<\/code><\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Learn how we migrated all Aspire docs from Learn to the new website aspire.dev learn<\/p>\n","protected":false},"author":24662,"featured_media":159,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1,17],"tags":[8,5,16],"class_list":["post-156","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-aspire-category","category-deep-dives","tag-ai","tag-aspire-dev","tag-copilot"],"acf":[],"blog_post_summary":"<p>Learn how we migrated all Aspire docs from Learn to the new website aspire.dev learn<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/posts\/156","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/users\/24662"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/comments?post=156"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/posts\/156\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/media\/159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/media?parent=156"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/categories?post=156"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/aspire\/wp-json\/wp\/v2\/tags?post=156"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}