Find out how to contribute a submit to evotec.xyz

Evotec is opening evotec.xyz to extra sensible voices from the group: individuals who construct, automate, migrate, troubleshoot, doc, and be taught in the true world.

You do not want to jot down an ideal article earlier than you begin. A helpful script, a hard-won lesson, an odd edge case, a migration be aware, or a transparent troubleshooting story can all turn out to be one thing helpful for different engineers.

This information explains methods to put together that article so it may be reviewed, improved, credited correctly, and revealed on evotec.xyz.

The aim is straightforward:

• make contributing approachable
• preserve overview predictable
• preserve publishing protected and constant
• give correct credit score to contributors
• assist extra individuals share sensible engineering information

Fast Model

In the event you already know GitHub and Markdown, that is the brief model:

1. Fork the Web site.Contributions repository.
2. Create your creator profile in authors/<your-slug>.yml.
3. Create your article folder in posts/<language>/<article-slug>/.
4. Add index.md, a canopy picture, and an photos/ folder for screenshots and article photos.
5. Write the article in Markdown.
6. Use native picture paths solely.
7. Commit your modifications.
8. Open a pull request.
9. Repair validation points if GitHub Actions stories any.
10. Look ahead to overview.

In case you are new to GitHub, Markdown, or pull requests, the remainder of this information walks by means of the method step-by-step.

Who This Information Is For

This information is for:

• first-time contributors
• individuals who have by no means opened a pull request
• people who find themselves undecided how the article folder ought to look
• individuals who have no idea the place photos go
• individuals who need a protected, repeatable course of

You do not should be an knowledgeable author. A centered, sensible article is often extra helpful than a protracted, summary one.

Good subjects embrace:

• PowerShell scripts that solved an actual downside
• Microsoft 365, Entra ID, Change, Lively Listing, Intune, Azure, or safety classes
• migration notes
• troubleshooting tales
• uncommon edge circumstances
• monitoring concepts
• dashboards and stories
• automation patterns
• open-source utilization
• classes realized from manufacturing work

Step 1: Open the Repository

Begin with the contribution repository:

https://github.com/EvotecIT/Web site.Contributions

You will want a GitHub account.

As soon as you’re on the repository web page, you have got two frequent methods to work.

Choice A — best for freshmen

Use the GitHub net interface within the browser.

That is the best possibility if:

• you don’t want to put in Git
• you don’t want to make use of command line instruments
• you need to preserve the whole lot easy

Choice B — native modifying

Clone the repository to your laptop and edit regionally utilizing instruments like:

• Visible Studio Code
• Git
• PowerShell
• your regular editor

In case you are undecided which path to decide on, use Choice A first.

Step 2: Fork the Repository

Click on Fork on GitHub.

A fork creates your personal copy of the repository beneath your GitHub account, so you may edit it safely.

In easy phrases:

• the unique repository stays unchanged
• you’re employed in your personal copy
• when you find yourself prepared, you open a pull request again to the unique repository

This retains the contribution course of protected and predictable.

Step 3: Select the Article Language

Articles stay beneath:

posts/<language>/<article-slug>/

The primary folder after posts/ is the language.

Examples:

posts/en/my-article-slug/
posts/pl/moj-artykul/

Use:

• en for English
• pl for Polish

Different web site interface languages could exist, however weblog contribution consumption ought to keep in en or pl until maintainers prolong the workflow. In case you are uncertain, use English.

Examples:

posts/en/how-to-check-dns-records/
posts/pl/jak-sprawdzic-rekordy-dns/

Step 4: Create Your Creator Profile

Each contributor ought to have an creator profile.

Create a file within the authors folder:

authors/your-name.yml

Instance:

title: "Your Identify"
slug: "your-name"
title: "Your position or brief bio"
avatar: "./photos/your-name.webp"
x: "https://x.com/your-handle"
linkedin: "https://www.linkedin.com/in/your-profile/"
github: "https://github.com/your-handle"
web site: "https://instance.com/"

You do not want each discipline. If you don’t use X, LinkedIn, GitHub, a private web site, or an avatar, pass over that discipline.

If you wish to present a profile photograph, place a sq. picture beneath authors/photos/ and reference it from the creator profile with avatar: "./photos/your-name.webp". Native avatars are non-compulsory and are imported into the web site along with the creator catalog.

A smaller legitimate instance can appear like this:

title: "Your Identify"
slug: "your-name"
title: "PowerShell fanatic and Microsoft engineer"
web site: "https://instance.com/"

Crucial rule is that the slug from the creator file should match the creator worth used within the article entrance matter.

Instance:

authors:
  - your-name

If these values don’t match, validation could fail or the article could not hyperlink to the creator accurately.

Step 5: Create the Article Folder

Every article ought to stay in its personal folder.

Use this form:

posts/en/my-article-slug/
  index.md
  cowl.webp
  photos/
    screenshot-01.webp

The construction means:

• posts/ — all posts
• en/ — the article language
• my-article-slug/ — the distinctive article folder
• index.md — the article itself
• cowl.webp — the duvet picture
• photos/ — screenshots and different article-specific photos

Preserve the whole lot for one article collectively in the identical article folder.

That makes overview simpler and avoids confusion when maintainers import the article into the manufacturing web site.

Step 6: Decide a Good Article Slug

The slug is the folder title used to your article.

Good slugs are:

• lowercase
• phrases separated by hyphens
• brief however descriptive
• secure

Good examples:

how-to-check-dns-records
find-stale-ad-computers
troubleshooting-exchange-mail-flow

Keep away from:

MyArticle
article1
test-post
new-final-version

A very good slug ought to describe the subject clearly.

Step 7: Create index.md

Contained in the article folder, create:

index.md

That file accommodates the article entrance matter and the precise content material.

Here’s a beginner-friendly starter template:

---
title: "Your Article Title"
description: "A brief abstract of what the article explains."
date: "2026-04-29"
language: "en"
authors:
  - your-name
classes:
  - PowerShell
tags:
  - powershell
  - automation
picture: "./cowl.webp"
image_alt: "Describe what the duvet picture exhibits"
draft: true
---

Begin with a brief introduction.

Clarify what downside you had, why it mattered, and what the reader will be taught.

## The Drawback

Describe the scenario clearly.

## The Answer

Clarify the answer step-by-step.

## Instance

Add code, screenshots, instructions, or configuration examples.

## End result

Present what the reader ought to anticipate.

## Wrap-Up

Summarize the lesson and point out something necessary to recollect.

The entrance matter fields on the prime describe the article.

Widespread fields are:

• title — the article title
• description — a brief abstract
• date — publication or preparation date
• language — article language, for instance en
• authors — a number of creator slugs
• classes — broader grouping
• tags — searchable key phrases
• picture — path to the duvet picture
• image_alt — alt textual content for the duvet picture
• draft — whether or not the submit remains to be a draft

Step 8: Add the Cowl Picture

Place the duvet picture subsequent to index.md.

For instance:

posts/en/my-article-slug/
  index.md
  cowl.webp

Accepted codecs:

.webp
.png
.jpg
.jpeg
.gif

Want .webp when potential as a result of it often provides good high quality with smaller file sizes.

Use .png when:

• the picture accommodates small textual content that should keep extraordinarily sharp
• the picture is a diagram and .webp makes it blurry
• the picture accommodates UI parts or code that turns into exhausting to learn in one other format

In case your cowl is a standard illustration or banner, .webp is often your best option.

Most popular cowl filename:

cowl.webp

Additionally acceptable if wanted:

cowl.png
cowl.jpg
cowl.jpeg
cowl.gif

Step 9: Add Screenshots and Different Photos

Put screenshots within the photos/ folder contained in the article folder.

Instance:

posts/en/my-article-slug/
  index.md
  cowl.webp
  photos/
    screenshot-01.webp
    powershell-output.png
    admin-center-setting.webp

Use descriptive names.

Good names:

photos/install-module-command.webp
photos/powershell-output.png
photos/entra-admin-center-setting.webp

Keep away from names like:

photos/image1.png
photos/remaining.png
photos/test2.webp

Descriptive names assist reviewers and future maintainers perceive what every file is for.

Step 10: Hyperlink Photos in Markdown

Use native relative paths solely.

Good instance:

![PowerShell output showing DNS lookup results](./photos/powershell-output.png)

Additionally good:

![Screenshot of the Entra admin center setting](./photos/entra-admin-center-setting.webp)

Keep away from distant photos:

![Screenshot](https://instance.com/screenshot.png)

Distant photos are a nasty match as a result of they’ll:

• disappear
• change
• be sluggish
• monitor readers
• break the article later

Alt Textual content Issues

Attempt to describe what the picture exhibits.

Good:

![GitHub pull request showing successful validation checks](./photos/pull-request-checks.webp)

Weak:

![image](./photos/pull-request-checks.webp)

Alt textual content helps with accessibility and in addition makes the content material extra comprehensible when photos don’t load.

Step 11: Write the Article in a Sensible Approach

The perfect articles are sensible and centered.

A helpful construction is:

1. What was the issue?
2. Why did it matter?
3. What did you do?
4. What instructions or steps had been used?
5. What end result did you get?
6. What ought to the reader be careful for?

That always turns into sections like this:

## The Drawback
## Necessities
## Step-by-Step Answer
## Code Instance
## End result
## Widespread Pitfalls
## Wrap-Up

Helpful writing ideas:

• preserve paragraphs readable
• present actual instructions when potential
• favor actual examples over obscure recommendation
• clarify portal paths clearly
• embrace screenshots if they assist
• embrace anticipated output when helpful
• point out permissions or necessities once they matter
• clarify frequent errors

Instance of a useful portal path:

Microsoft Entra admin heart
Identification > Functions > Enterprise functions > Consent and permissions

That sort of element saves readers time.

Step 12: Take away Delicate Data

Earlier than you commit something, overview all screenshots and examples rigorously.

Take away or blur:

• buyer names
• tenant names
• inner hostnames
• non-public IP addresses if not wanted
• e-mail addresses
• tokens
• secrets and techniques
• passwords
• license keys
• private knowledge
• inner incident particulars that shouldn’t be public

The place potential, use:

• demo knowledge
• lab environments
• redacted screenshots
• pretend pattern values

This issues so much for technical and security-related articles.

Step 13: Commit Your Adjustments

The way you do that depends upon how you’re modifying.

In the event you use GitHub within the browser

If you add or edit information, GitHub will supply a Commit modifications button.

Write a brief commit message reminiscent of:

Add article about checking DNS data with PowerShell

Then commit the modifications to your fork.

In the event you work regionally

Typical instructions appear like this:

git add .
git commit -m "Add article about checking DNS data with PowerShell"
git push

That pushes your work to your fork on GitHub.

Step 14: Open a Pull Request

As soon as your modifications are in your fork, open a pull request.

In easy phrases, a pull request says:

I made these modifications in my fork and I would love maintainers to overview them.

A very good pull request title is likely to be:

Add article: Find out how to verify DNS data with PowerShell

A helpful pull request description will be brief:

This PR provides a brand new article about checking DNS data with PowerShell.
It consists of the article markdown, cowl picture, screenshots, and creator profile.

Step 15: Look ahead to Validation Checks

After the pull request is opened, GitHub Actions validates the contribution mechanically.

Typical checks could embrace:

• article construction
• creator profile presence
• picture paths
• alt textual content
• file sizes
• anticipated folder structure

If a verify fails, don’t panic.

Often it means one thing small must be corrected.

Widespread examples:

• lacking creator file
• improper creator slug
• damaged picture path
• lacking alt textual content
• improper folder construction
• picture file too massive
• article lacking a required discipline

Repair the issue, commit once more, and the pull request will replace.

Step 16: Reply to Evaluation Suggestions

Generally a pull request is prepared rapidly.

Different occasions, maintainers could ask for enhancements reminiscent of:

• clearer title
• higher description
• safer screenshots
• extra context
• higher picture naming
• cleaner formatting
• clearer alt textual content

That could be a regular a part of the method.

The aim is to not make contributing tough. The aim is to make the ultimate submit protected, helpful, and simple to publish.

Step 17: What Occurs After Approval

If the article is accepted:

• maintainers merge or settle for the contribution
• maintainers import it into the manufacturing web site
• your creator credit score stays connected to the article

That half is dealt with by maintainers.

GitHub Internet UI Path for Complete Newcomers

If you’d like the best potential method, right here is the newbie path:

1. Open the repository on GitHub.
2. Click on Fork.
3. Open your fork.
4. Go to authors/.
5. Create your-name.yml.
6. Go to posts/en/ for English or posts/pl/ for Polish.
7. Create your article folder.
8. Add index.md.
9. Add cowl.webp, or one other accepted native picture format if wanted.
10. Create photos/.
11. Add screenshots into photos/.
12. Commit modifications.
13. Open a pull request.
14. Look ahead to checks.
15. Reply to suggestions if wanted.

This path is slower than native modifying, however it is rather pleasant for first-time contributors.

Elective: Native Enhancing Path

In the event you favor to work regionally, the method remains to be easy:

1. Fork the repository on GitHub.
2. Clone your fork regionally.
3. Create the creator profile.
4. Create the article folder.
5. Add index.md.
6. Add the duvet picture and screenshots.
7. Commit and push.
8. Open a pull request.

The folder construction stays precisely the identical.

Instance Ultimate Construction

Here’s a full instance:

authors/your-name.yml

posts/en/how-to-check-dns-records/
  index.md
  cowl.webp
  photos/
    powershell-output.png
    dns-zone-result.webp
    admin-center-setting.webp

And right here is how the article references the creator:

authors:
  - your-name

And right here is the way it references a picture:

![PowerShell output showing DNS lookup results](./photos/powershell-output.png)

FAQ

Do I want entry to the web site repository?

No. Begin within the contribution repository. Maintainers deal with the publishing step after overview.

Can I write in English?

Sure.

Can I write in Polish?

Sure. Use posts/pl/ for Polish articles. The present weblog contribution consumption makes use of en and pl.

Ought to I exploit .webp or .png?

Use .webp when potential. Use .png when picture readability, sharp textual content, or diagram precision issues extra. The validator additionally accepts .jpg, .jpeg, and .gif when these codecs are a greater match.

Do I want to put in Git?

No, not if you happen to use the GitHub net interface.

Can I contribute even when I’m new to Markdown?

Sure. A easy, clearly structured article is sufficient.

Can I replace the article after opening the pull request?

Sure. Add extra commits to your department or replace the information in GitHub. The pull request will replace mechanically.

What if GitHub Actions fails?

Open the failed verify, learn the message, repair the difficulty, and commit once more.

Can I add a couple of creator?

Sure, if the repository and article format assist it. Use a number of slugs within the authors part.

Instance:

authors:
  - your-name
  - second-author

Can I submit an article with out screenshots?

Sure, if screenshots aren’t wanted. If screenshots assist clarify the subject, embrace them.

Can I exploit distant picture URLs?

No. Preserve photos native to the article folder.

Troubleshooting

My picture just isn’t displaying

Examine:

• the file exists
• the filename matches precisely
• the trail is right
• the extension is right
• you referenced ./photos/... if the file is inside photos/

My creator profile just isn’t linked

Examine:

• the creator file exists in authors/
• the slug is right
• the article makes use of the identical slug in entrance matter

I’m not positive the place the duvet picture goes

The quilt picture goes subsequent to index.md, not inside photos/.

Appropriate:

posts/en/my-article-slug/
  index.md
  cowl.webp
  photos/

I’m not positive the place screenshots go

Screenshots go inside photos/.

I’m not positive what language folder to make use of

Use en for English and pl for Polish. In case you are uncertain, use en.

Ultimate Guidelines Earlier than Opening a Pull Request

Earlier than you open the pull request, verify this record:

Ultimate Ideas

The contribution course of is supposed to be easy:

• write within the contribution repository
• enhance the article by means of overview
• publish by means of maintainers
• preserve publishing protected and constant
• give contributors correct credit score

When you’ve got one thing helpful to share, even when it’s a small sensible tip, that is sufficient to begin.

A very good technical article doesn’t should be enormous. It simply must be helpful.